We use cookies (just for analytics) on this website. If you continue we will assume you are happy with it. ok

BeBanjo

Back to index

Rendition

Note: This resource links can be expanded using the expand option except the asset link.

The rendition resource refers to a Video rendition of a specific Asset. In Movida an asset normally represents an Editorial Version of a given feature or episode of a series (i.e. with or without violence, with or without ads, etc.), and that Editorial Version can be then held in multiple video renditions (different bit rates, different video formats, etc.)

This is how a rendition looks through the API:

<?xml version='1.0' encoding='utf-8' ?>
<rendition>
  <id type="integer">73</id>
  <external_id>ABCD00001</external_id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding nil="true"/>
  <aspect-ratio>16:9</aspect-ratio> <!-- Valid format: two numbers separated by : or / -->
  <color>black_and_white</color> <!-- Valid values: color, colorized, black_and_white, black_and_white_and_color -->
  <frame-rate nil="true"/> <!-- Valid values: positive numbers with or without decimals -->
  <scan>interlaced</scan> <!-- Valid values: interlaced, progressive -->
  <bit-rate-minimum type="integer">600</bit-rate-minimum>
  <bit-rate-maximum type="integer">1200</bit-rate-maximum>
  <bit-rate-average type="integer">1000</bit-rate-average>
  <bit-rate-variable type="boolean">true</bit-rate-variable>
  <file-name>wadus.mp4</file-name>
  <file-size type="integer">1073741824</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <runtime type="duration">00:34:20.000</runtime>
  <link rel="self" href="https://movida.bebanjo.net/api/renditions/73"/>
  <link rel="file" href="https://example.com/wadus.mp4"/>
  <link rel="audio_tracks" href="https://movida.bebanjo.net/api/renditions/73/audio_tracks"/>
  <link rel="subtitles" href="https://movida.bebanjo.net/api/renditions/73/subtitles"/>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/renditions/73/target_platforms"/>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/372"/>
</rendition>

Valid attributes

  • color: The field color is validated when it’s specified. The list of allowed values is: color, colorized, black_and_white, black_and_white_and_color.

  • frame-rate: The field frame-rate is validated when it’s specified. The valid value has to be positive numbers with or without decimals.

  • scan: The field scan is validated when it’s specified. The list of allowed values is: interlaced, progressive.

  • aspect-ratio: The field aspect-ratio is validated when it’s specificed. The valid format is two numbers separated by : or / (eg. 4:3, 16/9 or 1.85:1)

  • file-name: The field file-name is validated when it’s specified. It should be a valid filename without spaces and other special characters like #, $, [], {}, @…

  • rel="file": This field should be a valid URI

  • runtime: (optional): the runtime of the rendition. Format “hh:mm:ss.mmm”. The miliseconds are optional, a rendition with 01:01:01 is valid, it’s assumed 0 milliseconds.

Get a list of all renditions in the current account

Renditions are linked from the root of the API, through the link identified with the rel="renditions" attribute:

<?xml version="1.0" encoding="UTF-8"?>
<movida>
  <!-- ... -->
  <link rel="renditions" href="https://movida.bebanjo.net/api/renditions">
</movida>

Following that link, we can fetch the list of renditions in the current account.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/renditions
<?xml version="1.0" encoding="UTF-8"?>
<renditions>
  <total-entries>1143</total-entries>
  <link rel="next" href="https://movida.bebanjo.net/api/renditions?page=1"/>
  <link rel="prev" href="https://movida.bebanjo.net/api/renditions?page=3"/>
  <rendition>
    <id type="integer">73</id>
    <external_id>ABCD00001</external_id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding nil="true"/>
    <aspect-ratio>16:9</aspect-ratio>
    <color>black_and_white</color>
    <frame-rate nil="true"/>
    <scan>interlaced</scan>
    <bit-rate-minimum type="integer">600</bit-rate-minimum>
    <bit-rate-maximum type="integer">1200</bit-rate-maximum>
    <bit-rate-average type="integer">1000</bit-rate-average>
    <bit-rate-variable type="boolean">true</bit-rate-variable>
    <file-name>wadus.mp4</file-name>
    <file-size type="integer">1073741824</file-size>
    <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
    <runtime type="duration">00:34:20.000</runtime>
    <link rel="self" href="https://movida.bebanjo.net/api/renditions/73"/>
    <link rel="file" href="https://example.com/wadus.mp4"/>
    <link rel="audio_tracks" href="https://movida.bebanjo.net/api/renditions/73/audio_tracks"/>
    <link rel="subtitles" href="https://movida.bebanjo.net/api/renditions/73/subtitles"/>
    <link rel="target_platforms" href="https://movida.bebanjo.net/api/renditions/73/target_platforms"/>
    <link rel="asset" href="https://movida.bebanjo.net/api/assets/372"/>
  </rendition>
  <rendition>
    <id type="integer">832</id>
    <external_id>ABCD00802</external_id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding nil="true"/>
    <aspect-ratio>16:9</aspect-ratio>
    <color>color</color>
    <frame-rate nil="true"/>
    <scan>progressive</scan>
    <bit-rate-minimum type="integer">600</bit-rate-minimum>
    <bit-rate-maximum type="integer">1200</bit-rate-maximum>
    <bit-rate-average type="integer">1000</bit-rate-average>
    <bit-rate-variable type="boolean">true</bit-rate-variable>
    <file-name>foo.mp4</file-name>
    <file-size type="integer">1072630713</file-size>
    <file-md5>1bbc4c41ea74053cc550972ab4206d</file-md5>
    <runtime type="duration">00:41:17.000</runtime>
    <link rel="self" href="https://movida.bebanjo.net/api/renditions/832"/>
    <link rel="file" href="https://example.com/foo.mp4"/>
    <link rel="audio_tracks" href="https://movida.bebanjo.net/api/renditions/832/audio_tracks"/>
    <link rel="subtitles" href="https://movida.bebanjo.net/api/renditions/832/subtitles"/>
    <link rel="target_platforms" href="https://movida.bebanjo.net/api/renditions/832/target_platforms"/>
    <link rel="asset" href="https://movida.bebanjo.net/api/assets/102"/>
  </rendition>
  <!-- ... -->
<renditions>

Note: This is a paginated resource. By default, only 50 renditions will be included in each page but you can override this default by using the per_page parameter described in the next section. The total-entries attribute will indicate the total number of entries and the links rel="next" and rel="prev" should be used to get the next and the previous pages.

Valid attributes

You can filter the list of renditions returned using the following attributes:

  • external_id: It will return only the rendition with the exact given external_id (if any).

  • per_page: Number of elements returned in each page. The maximum value allowed is 200 and the default is 50.

Get a list for all renditions for an asset

renditions are accessed via the Asset they belong to, as in the example below, through the link identified by the rel=”renditions” attribute:

<?xml version='1.0' encoding='utf-8' ?>
<assets type="array">
  <asset>
    <name>Film</name>
    <link href="https://movida.bebanjo.net/api/titles/163/assets/46/metadata" rel="metadata"/>
    <link href="https://movida.bebanjo.net/api/assets/46/renditions" rel="renditions"/>
  </asset>
</assets>

If we follow that link, we can fetch the list of all renditions for that asset.

$ curl --digest -u roboot_user:password https://movida.bebanjo.net/api/assets/46/renditions
<?xml version="1.0" encoding="UTF-8"?>
<renditions type="array">
  <rendition>
    <id type="integer">73</id>
    <external_id>ABCD00001</external_id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding>H264</encoding>
    <aspect-ratio>16:9</aspect-ratio>
    <color>black_and_white</color>
    <frame-rate nil="true"/>
    <scan>interlaced</scan>
    <bit-rate-minimum type="integer">600</bit-rate-minimum>
    <bit-rate-maximum type="integer">1200</bit-rate-maximum>
    <bit-rate-average type="integer">1000</bit-rate-average>
    <bit-rate-variable type="boolean">true</bit-rate-variable>
    <file-name>wadus.mp4</file-name>
    <file-size type="integer">1073741824</file-size>
    <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
    <runtime type="duration">00:34:20.000</runtime>
    <link rel="self" href="https://movida.bebanjo.net/api/renditions/73"/>
    <link rel="file" href="https://example.com/wadus.mp4"/>
    <link rel="audio_tracks" href="https://movida.bebanjo.net/api/renditions/73/audio_tracks"/>
    <link rel="subtitles" href="https://movida.bebanjo.net/api/renditions/73/subtitles"/>
    <link rel="target_platforms" href="https://movida.bebanjo.net/api/renditions/73/target_platforms"/>
    <link rel="asset" href="https://movida.bebanjo.net/api/assets/46"/>
  </rendition>
  <rendition>
    <id type="integer">74</id>
    <external_id>ABCD00002</external_id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding>H264</encoding>
    <aspect-ratio>16:9</aspect-ratio>
    <color>black_and_white</color>
    <frame-rate nil="true"/>
    <scan>interlaced</scan>
    <bit-rate-minimum>600</bit-rate-minimum>
    <bit-rate-maximum>1200</bit-rate-maximum>
    <bit-rate-average>1000</bit-rate-average>
    <bit-rate-variable type="boolean">false</bit-rate-variable>
    <file-name>wadus.mp4</file-name>
    <file-size type="integer">1073741824</file-size>
    <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
    <runtime type="duration">00:38:10.000</runtime>
    <link rel="self" href="https://movida.bebanjo.net/api/renditions/74"/>
    <link rel="file" href="https://example.com/wadus.mp4"/>
    <link rel="audio_tracks" href="https://movida.bebanjo.net/api/renditions/74/audio_tracks"/>
    <link rel="subtitles" href="https://movida.bebanjo.net/api/renditions/74/subtitles"/>
    <link rel="target_platforms" href="https://movida.bebanjo.net/api/renditions/74/target_platforms"/>
    <link rel="asset" href="https://movida.bebanjo.net/api/assets/46"/>
  </rendition>
</renditions>

Each rendition has a link to its parent asset; this enables an integration that doesn’t store a reference to the asset (i.e. it only references the rendition) to easily find the parent asset, then the title, etc.

$ curl --digest -u roboot_user:password https://movida.bebanjo.net/api/assets/46

Get a specific rendition

This a good way to recover information about a specific rendition.

$ curl --digest -u roboot_user:password https://movida.bebanjo.net/api/renditions/73
<?xml version="1.0" encoding="UTF-8"?>
<rendition>
  <id type="integer">73</id>
  <external_id>ABCD00001</external_id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding>H264</encoding>
  <color>black_and_white</color>
  <frame-rate nil="true"/>
  <scan>interlaced</scan>
  <aspect-ratio>16:9</aspect-ratio>
  <bit-rate-minimum>600</bit-rate-minimum>
  <bit-rate-maximum>1200</bit-rate-maximum>
  <bit-rate-average>1000</bit-rate-average>
  <bit-rate-variable type="boolean">false</bit-rate-variable>
  <file-name>wadus.mp4</file-name>
  <file-size type="integer">1073741824</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <runtime type="duration">01:14:20.000</runtime>
  <link rel="self" href="https://movida.bebanjo.net/api/renditions/73"/>
  <link rel="file" href="https://example.com/wadus.mp4"/>
  <link rel="audio_tracks" href="https://movida.bebanjo.net/api/renditions/73/audio_tracks"/>
  <link rel="subtitles" href="https://movida.bebanjo.net/api/renditions/73/subtitles"/>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/renditions/73/target_platforms"/>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/372"/>
</rendition>

Remember you can use the expand me some nodes trick if you want to, for instance, find out what is the subtitles and audio_tracks of a particular rendition.

$ curl --digest -u roboot_user:password https://movida.bebanjo.net/api/renditions/73?expand=audio_tracks,subtitles,target_platforms

This would expand the rel="audio_tracks" link, and then would also expand the rel="subtitles" link inside the rendition and the target platforms, yielding something like:

<?xml version="1.0" encoding="UTF-8"?>
<rendition>
  <id type="integer">77</id>
  <external_id>ABCD00006</external_id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding nil="true"/>
  <color>black_and_white_and_color</color>
  <frame-rate nil="true"/>
  <scan>interlaced</scan>
  <aspect-ratio>16:9</aspect-ratio>
  <bit-rate-minimum>600</bit-rate-minimum>
  <bit-rate-maximum>1200</bit-rate-maximum>
  <bit-rate-average>1000</bit-rate-average>
  <bit-rate-variable type="boolean">false</bit-rate-variable>
  <file-name>wadus.mp4</file-name>
  <file-size type="integer">1073741824</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <runtime type="duration">00:34:20.000</runtime>
  <link rel="self" href="https://movida.bebanjo.net/api/renditions/77"/>
  <link rel="file" href="https://example.com/wadus.mp4"/>
  <link rel="audio_tracks" href="https://movida.bebanjo.net/api/renditions/77/audio_tracks">
    <audio-tracks type="array">
      <audio-track>
        <id type="integer">27</id>
        <language>eng</language>
        <original-version type="boolean">true</original-version>
        <encoding>WMA9</encoding>
        <mix-type>Dolby Digital</mix-type>
        <channels>5.1</channels>
        <link rel="self" href="https://movida.bebanjo.net/api/audio_tracks/27"/>
      </audio-track>
    </audio-tracks>
  </link>
  <link rel="subtitles" href="https://movida.bebanjo.net/api/renditions/77/subtitles">
    <subtitles type="array">
      <subtitle>
        <id type="integer">16</id>
        <language>eng</language>
        <burnt-in type="boolean">false</burnt-in>
        <for-the-hearing-impaired type="boolean">false</for-the-hearing-impaired>
        <file-name>subtitle.srt</file-name>
        <file-size type="integer">1024</file-size>
        <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
        <link rel="self" href="https://movida.bebanjo.net/api/subtitles/16"/>
        <link rel="file" href="https://example.com/subtitle.srt"/>
      </subtitle>
    </subtitles>
  </link>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/renditions/77/target_platforms">
    <target-platforms type="array">
      <target-platform>
        <link rel="self" href="https://movida.bebanjo.net/api/target_platforms/11"/>
        <link rel="platform" href="https://movida.bebanjo.net/api/platforms/1"/>
      </target-platform>
    </target-platforms>
  </link>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/372"/>
</rendition>

Creating a new rendition for an asset

To create a rendition, you just need to POST a proper XML rendition representation (similar to the ones you get when fetching a rendition) to the proper URL. As explained above, that URL is in the link node whose rel attribute equals renditions.

For example, this POST would create a rendition (we’ll use curl’s @ option, which reads the data that is to be posted to the URL from a file):

cat rendition.xml
<rendition>
  <external_id>ABCD9982</external_id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding>H264</encoding>
  <color>black_and_white</color>
  <frame-rate>29.97</frame-rate>
  <scan>interlaced</scan>
  <bit-rate-minimum>600</bit-rate-minimum>
  <bit-rate-maximum>1200</bit-rate-maximum>
  <bit-rate-average>1000</bit-rate-average>
  <bit-rate-variable type="boolean">false</bit-rate-variable>
  <file-name>wadus.mp4</file-name>
  <file-size type="integer">1073741824</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="file" href="https://example.com/wadus.mp4"/>
</rendition>
$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @rendition.xml "https://movida.bebanjo.net/api/assets/46/renditions"

Movida will return the full XML of the rendition just created:

<?xml version="1.0" encoding="UTF-8"?>
<rendition>
  <id type="integer">73</id>
  <external_id>ABCD9982</external_id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding>H264</encoding>
  <color>black_and_white</color>
  <frame-rate>29.97</frame-rate>
  <scan>interlaced</scan>
  <bit-rate-minimum>600</bit-rate-minimum>
  <bit-rate-maximum>1200</bit-rate-maximum>
  <bit-rate-average>1000</bit-rate-average>
  <bit-rate-variable type="boolean">false</bit-rate-variable>
  <file-name>wadus.mp4</file-name>
  <file-size type="integer">1073741824</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://movida.bebanjo.net/api/renditions/73"/>
  <link rel="file" href="https://example.com/wadus.mp4"/>
  <link rel="audio_tracks" href="https://movida.bebanjo.net/api/renditions/73/audio_tracks"/>
  <link rel="subtitles" href="https://movida.bebanjo.net/api/renditions/73/subtitles"/>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/renditions/73/target_platforms"/>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/46"/>
</rendition>

Updating a rendition

As our introduction to REST APIs guide suggests, you can update a rendition using a PUT request to each rendition URI. You only need to include those attributes of the rendition that you wish to update:

cat rendition_update.xml
<rendition>
  <width>800</width>
  <height>600</height>
  <encoding>H264</encoding>
  <color>color</color>
  <link rel="file" href="https://example.com/wadus_color.mp4"/>
</rendition>
$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @rendition_update.xml "https://movida.bebanjo.net/api/renditions/73"

As always Movida will return the full XML of the rendition just updated:

<rendition>
  <id type="integer">73</id>
  <external_id>ABCD9982</external_id>
  <width type="integer">800</width>
  <height type="integer">600</height>
  <encoding>H264</encoding>
  <color>color</color>
  <frame-rate nil="true"/>
  <scan>interlaced</scan>
  <bit-rate-minimum>600</bit-rate-minimum>
  <bit-rate-maximum>1200</bit-rate-maximum>
  <bit-rate-average>1000</bit-rate-average>
  <bit-rate-variable type="boolean">false</bit-rate-variable>
  <file-name>wadus.mp4</file-name>
  <file-size type="integer">1073741824</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://movida.bebanjo.net/api/renditions/73"/>
  <link rel="file" href="https://example.com/wadus_color.mp4"/>
  <link rel="audio_tracks" href="https://movida.bebanjo.net/api/renditions/73/audio_tracks"/>
  <link rel="subtitles" href="https://movida.bebanjo.net/api/renditions/73/subtitles"/>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/renditions/73/target_platforms"/>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/372"/>
</rendition>

Deleting a rendition

You can also delete a rendition using DELETE request to each rendition URI:

$ curl --digest -u robot_user:password -X DELETE "https://movida.bebanjo.net/api/renditions/73"

Note: Deleting a rendition doesn’t delete related resources such as audio tracks or subtitles. You should manually delete them.

Last updated October 10th, 2017.