Skip to content

Developers

How can we help you?

← Go back

Subtitle

This resource represents a specific subtitle (either a subtitle file or a burnt in subtitle) for a given rendition. A subtitle can be in a given language, can be for-the-hearing-impaired or not and can be burnt in the video or within a given subtitle file that can accompany the rendition.

This is how a subtitle looks like when accessed via the Mediagenix On-Demand API:

<?xml version='1.0' encoding='utf-8' ?>
<subtitle>
  <id type="integer">13</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">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://movida.bebanjo.net/api/subtitles/13"/>
  <link rel="file" href="https://wadus.bebanjo.net/subtitle.srt"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/subtitles/13/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/1"/>
</subtitle>

{
  "resource_type": "subtitle",
  "id": 13,
  "language": "eng",
  "burnt_in": false,
  "for_the_hearing_impaired": false,
  "file_name": "subtitle.srt",
  "file_size": 2345569434,
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "self_link": "https://movida.bebanjo.net/api/subtitles/13",
  "file_link": "https://wadus.bebanjo.net/subtitle.spa.srt",
  "metadata_link": "https://movida.bebanjo.net/api/subtitles/13/metadata",
  "rendition_link": "https://movida.bebanjo.net/api/renditions/1"
}

Valid attributes

  • language: The language attribute is validated and required. List of possible languages as per ISO 639-2/T codes by name. See http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes.

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

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

Get a list of all subtitles for a rendition

Subtitles are accessed via the Rendition they belong to, as in the example below, through the link identified by the rel="subtitles" attribute. Refer to the [[Mediagenix On-Demand Resource: Rendition]] page to find out how to access a Rendition.

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

{
  "resource_type": "rendition",
  // ...
  "subtitles_link": "https://movida.bebanjo.net/api/renditions/39/subtitles",
  // ...
}

If we follow that link we can fetch the list of all subtitles for that rendition:

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/renditions/39/subtitles

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/renditions/39/subtitles

<?xml version="1.0" encoding="UTF-8"?>
<subtitles type="array">
 <subtitle>
  <id type="integer">13</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">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://movida.bebanjo.net/api/subtitles/13"/>
  <link rel="file" href="https://wadus.bebanjo.net/subtitle.srt"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/subtitles/13/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
 </subtitle>
 <subtitle>
  <id type="integer">14</id>
  <language>spa</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">2345569433</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b8</file-md5>
  <link rel="self" href="https://movida.bebanjo.net/api/subtitles/14"/>
  <link rel="file" href="https://wadus.bebanjo.net/subtitle.srt"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/subtitles/14/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
 </subtitle>
</subtitles>

{
  "entries": [
    {
      "resource_type": "subtitle",
      "id": 13,
      "language": "eng",
      "burnt_in": false,
      "for_the_hearing_impaired": false,
      "file_name": "subtitle.srt",
      "file_size": 2345569434,
      "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
      "self_link": "https://movida.bebanjo.net/api/subtitles/13",
      "file_link": "https://example.com/subtitle.srt",
      "metadata_link": "https://movida.bebanjo.net/api/subtitles/13/metadata",
      "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
    },
    {
      "resource_type": "subtitle",
      "id": 14,
      "language": "spa",
      "burnt_in": false,
      "for_the_hearing_impaired": false,
      "file_name": "subtitle.srt",
      "file_size": 2345569433,
      "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b8",
      "self_link": "https://movida.bebanjo.net/api/subtitles/14",
      "file_link": "https://wadus.bebanjo.net/subtitle.srt",
      "metadata_link": "https://movida.bebanjo.net/api/subtitles/14/metadata",
      "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
    }
  ]
}

Get a specific subtitle

This is how we would recover information about a specific subtitle:

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/subtitles/23

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/subtitles/23

<?xml version="1.0" encoding="UTF-8"?>
<subtitle>
  <id type="integer">13</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">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://movida.bebanjo.net/api/subtitles/13"/>
  <link rel="file" href="https://wadus.bebanjo.net/subtitle.srt"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/subtitles/13/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
</subtitle>

{
  "resource_type": "subtitle",
  "id": 13,
  "language": "eng",
  "burnt_in": false,
  "for_the_hearing_impaired": false,
  "file_name": "subtitle.srt",
  "file_size": 2345569434,
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "self_link": "https://movida.bebanjo.net/api/subtitles/13",
  "file_link": "https://example.com/subtitle.srt",
  "metadata_link": "https://movida.bebanjo.net/api/subtitles/13/metadata",
  "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
}

Creating subtitles for a rendition

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

For example, the following XML/JSON issued as a POST to the subtitles URL of a rendition would create a subtitle (we’ll use curl’s @ option, which reads data to be posted from a file):

$ cat subtitle.xml

$ cat subtitle.json

<subtitle>
  <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">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="file" href="https://wadus.bebanjo.net/subtitle.srt"/>
</subtitle>

{
  "language": "eng",
  "burnt_in": "false",
  "for_the_hearing_impaired": "false",
  "file_name": "subtitle.srt",
  "file_size": 2345569434,
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "file_link": "https://wadus.bebanjo.net/subtitle.srt"
}

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @subtitle.xml "https://movida.bebanjo.net/api/renditions/39/subtitles"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @subtitle.json "https://movida.bebanjo.net/api/renditions/39/subtitles"

Mediagenix On-Demand will return the full XML/JSON of the subtitle just created:

<?xml version="1.0" encoding="UTF-8"?>
<subtitle>
  <id type="integer">13</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">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://movida.bebanjo.net/api/subtitles/13"/>
  <link rel="file" href="https://wadus.bebanjo.net/subtitle.srt"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/subtitles/13/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
</subtitle>

{
  "resource_type": "subtitle",
  "id": 13,
  "language": "eng",
  "burnt_in": false,
  "for_the_hearing_impaired": false,
  "file_name": "subtitle.srt",
  "file_size": 2345569434,
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "self_link": "https://movida.bebanjo.net/api/subtitles/13",
  "file_link": "https://wadus.bebanjo.net/subtitle.srt",
  "metadata_link": "https://movida.bebanjo.net/api/subtitles/13/metadata",
  "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
}

Updating a subtitle

As our introduction to REST APIs guide page suggests, you can update a subtitle issuing a PUT request to each subtitle URI:

$ cat subtitle_update.xml

$ cat subtitle_update.json

<subtitle>
 <language>spa</language>
 <burnt-in>true</burnt-in>
 <link rel="file" href="https://wadus.bebanjo.net/subtitle.spa.srt"/>
</subtitle>

{
  "language": "spa",
  "burnt_in": true,
  "file_link": "https://wadus.bebanjo.net/subtitle.spa.srt"
}

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @subtitle_update.xml "https://movida.bebanjo.net/api/subtitles/13"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X PUT -d @subtitle_update.json "https://movida.bebanjo.net/api/subtitles/13"

As always Mediagenix On-Demand will return the full XML/JSON of the subtitle just updated:

<?xml version="1.0" encoding="UTF-8"?>
<subtitle>
  <id type="integer">13</id>
  <language>spa</language>
  <burnt-in type="boolean">true</burnt-in>
  <for-the-hearing-impaired type="boolean">false</for-the-hearing-impaired>
  <file-name>subtitle.srt</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://movida.bebanjo.net/api/subtitles/13"/>
  <link rel="file" href="https://wadus.bebanjo.net/subtitle.spa.srt"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/subtitles/13/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
</subtitle>

{
  "resource_type": "subtitle",
  "id": 13,
  "language": "spa",
  "burnt_in": true,
  "for_the_hearing_impaired": false,
  "file_name": "subtitle.srt",
  "file_size": 2345569434,
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "self_link": "https://movida.bebanjo.net/api/subtitles/13",
  "file_link": "https://wadus.bebanjo.net/subtitle.spa.srt",
  "metadata_link": "https://movida.bebanjo.net/api/subtitles/13/metadata",
  "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
}

Deleting a subtitle

Also you can delete a subtitle using DELETE request to each subtitle URI:

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

$ curl --digest -u robot_user:password -H "Accept: application/json" -X DELETE "https://movida.bebanjo.net/api/subtitles/13"

File Name Validation

Note that the Mediagenix On-Demand API validates the file name for subtitle files. If the file name in a given request includes one or more restricted characters, then the response body for the 4xx error will include the “The request could not be processed by the server due to malformed syntax” message. Please review the Status Codes and Errors page for the full list of restricted characters and associated HTTP status codes.