Skip to content

Developers

How can we help you?

← Go back

Audio track

The audio track resource represents an audio track within a rendition. For instance, a specific rendition could have multiple audio tracks (original version, dubbed version and the original version in Dolby digital). It is assumed that audio tracks are contained within a rendition and are not separate audio files, although this could change in the future.

This is how an audio track looks like through the API:

<?xml version='1.0' encoding='utf-8' ?>
<audio-track>
  <id type="integer">16</id>
  <language>eng</language>
  <original-version type="boolean">true</original-version>
  <encoding>WMA9</encoding>
  <mix-type>Dolby Digital</mix-type>
  <channels>5.1</channels>
  <audio-description type="boolean">true</audio-description>
  <file-name>audio.mp3</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://movida.bebanjo.net/api/audio_tracks/16"/>
  <link rel="file" href="https://wadus.bebanjo.net/audio.mp3"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/audio_tracks/16/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
</audio-track>

{
  "resource_type": "audio_track",
  "id": 16,
  "language": "eng",
  "original_version": true,
  "encoding": "WMA9",
  "mix_type": "Dolby Digital",
  "channels": "5.1",
  "audio_description": true,
  "file_name": "audio.mp3",
  "file_size": 2345569434,
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "self_link": "https://movida.bebanjo.net/api/audio_tracks/16",
  "file_link": "https://wadus.bebanjo.net/audio.mp3",
  "metadata_link": "https://movida.bebanjo.net/api/audio_tracks/16/metadata",
  "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
}

Valid attributes

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

  • original-version (optional). By default false. Defines if an audio track is the original version one.

  • encoding (optional). The encoding of the audio track. Any value is allowed.

  • mix-type (optional). Defines the mix type. Any value is allowed.

  • channels (optional). Defines the number of channels. Any value is allowed.

  • audio-description (optional). Defines if the audio track contains a narrative track with audio description for the visually impaired. The following values are allowed: nil, “true” and “false”.

  • 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 for all audio tracks for a rendition

Audio tracks are accessed via the Rendition they belong to, as in the example below, through the link identified by the rel=”audio_tracks” 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="audio_tracks" href="https://movida.bebanjo.net/api/renditions/39/audio_tracks"/>
 <!-- ... -->
</rendition>

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

If we follow that link, we can fetch the list of all audio tracks for that rendition.

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

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

<?xml version="1.0" encoding="UTF-8"?>
<audio-tracks type="array">
  <audio-track>
    <id type="integer">16</id>
    <language>eng</language>
    <original-version type="boolean">true</original-version>
    <encoding>WMA9</encoding>
    <mix-type>Dolby Digital</mix-type>
    <channels>5.1</channels>
    <audio-description nil="true"/>
    <file-name>audio.mp3</file-name>
    <file-size type="integer">2345569434</file-size>
    <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
    <link rel="self" href="https://www.example.com/api/audio_tracks/16"/>
    <link rel="file" href="https://wadus.bebanjo.net/audio.mp3"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/audio_tracks/16/metadata"/>
    <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
  </audio-track>
  <audio-track>
    <id type="integer">17</id>
    <language>eng</language>
    <original-version type="boolean">true</original-version>
    <encoding>WMA9</encoding>
    <mix-type>Dolby Digital</mix-type>
    <channels>5.1</channels>
    <audio-description nil="true"/>
    <file-name>audio.mp3</file-name>
    <file-size type="integer">2345569434</file-size>
    <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
    <link rel="self" href="https://www.example.com/api/audio_tracks/17"/>
    <link rel="file" href="https://wadus.bebanjo.net/audio.mp3"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/audio_tracks/17/metadata"/>
    <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
  </audio-track>
</audio-tracks>

{
  "entries": [
    {
      "resource_type": "audio_track",
      "id": 16,
      "language": "eng",
      "original_version": true,
      "encoding": "WMA9",
      "mix_type": "Dolby Digital",
      "channels": "5.1",
      "audio_description": null,
      "file_name": "audio.mp3",
      "file_size": 2345569434,
      "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
      "self_link": "https://movida.bebanjo.net/api/audio_tracks/16",
      "file_link": "https://wadus.bebanjo.net/audio.mp3",
      "metadata_link": "https://movida.bebanjo.net/api/audio_tracks/16/metadata",
      "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
    },
    {
      "resource_type": "audio_track",
      "id": 17,
      "language": "eng",
      "original_version": true,
      "encoding": "WMA9",
      "mix_type": "Dolby Digital",
      "channels": "5.1",
      "audio_description": null,
      "file_name": "audio.mp3",
      "file_size": 2345569434,
      "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
      "self_link": "https://movida.bebanjo.net/api/audio_tracks/17",
      "file_link": "https://wadus.bebanjo.net/audio.mp3",
      "metadata_link": "https://movida.bebanjo.net/api/audio_tracks/17/metadata",
      "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
    }
  ]
}

Get a specific audio track

This how you recover information about a specific audio track.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/audio_tracks/17

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

<?xml version="1.0" encoding="UTF-8"?>
<audio-track>
  <id type="integer">17</id>
  <language>eng</language>
  <original-version type="boolean">true</original-version>
  <encoding>WMA9</encoding>
  <mix-type>Dolby Digital</mix-type>
  <channels>5.1</channels>
  <audio-description nil="true"/>
  <file-name>audio.mp3</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://www.example.com/api/audio_tracks/17"/>
  <link rel="file" href="https://wadus.bebanjo.net/audio.mp3"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/audio_tracks/17/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
</audio-track>

{
  "resource_type": "audio_track",
  "id": 17,
  "language": "eng",
  "original_version": null,
  "encoding": "WMA9",
  "mix_type": "Dolby Digital",
  "channels": "5.1",
  "audio_description": null,
  "file_name": "audio.mp3",
  "file_size": 2345569434,
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "self_link": "https://movida.bebanjo.net/api/audio_tracks/17",
  "file_link": "https://wadus.bebanjo.net/audio.mp3",
  "metadata_link": "https://movida.bebanjo.net/api/audio_tracks/17/metadata",
  "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
}

Creating audio tracks for a rendition

To create an audio track, you just need to POST a proper XML/JSON audio track representation (similar to the ones you get when fetching an audio track) to the proper URL. As explained above, that URL is in the link node whose ‘rel’ attribute equals ‘audio_tracks’.

For example, this POST would create an audio track (we’ll use curl’s @ option, which reads data to be posted from a file):

$ cat audio_track.xml

$ cat audio_track.json

<audio-track>
  <language>eng</language>
  <original-version type="boolean">true</original-version>
  <encoding>WMA9</encoding>
  <mix-type>Dolby Digital</mix-type>
  <channels>5.1</channels>
  <audio-description nil="true"/>
  <file-name>audio.mp3</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="file" href="https://wadus.bebanjo.net/audio.mp3"/>
</audio-track>

{
  "language": "eng",
  "encoding": "WMA9",
  "mix_type": "Dolby Digital",
  "channels": "5.1",
  "audio_description": null,
  "file_name": "audio.mp3",
  "file_size": "2345569434",
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "file_link": "https://wadus.bebanjo.net/audio.mp3"
}

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<audio-track>
  <id type="integer">17</id>
  <language>eng</language>
  <original-version type="boolean">true</original-version>
  <encoding>WMA9</encoding>
  <mix-type>Dolby Digital</mix-type>
  <channels>5.1</channels>
  <audio-description nil="true"/>
  <file-name>audio.mp3</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://www.example.com/api/audio_tracks/17"/>
  <link rel="file" href="https://wadus.bebanjo.net/audio.mp3"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/audio_tracks/17/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
</audio-track>

{
  "resource_type": "audio_track",
  "id": 17,
  "language": "eng",
  "original_version": null,
  "encoding": "WMA9",
  "mix_type": "Dolby Digital",
  "channels": "5.1",
  "audio_description": null,
  "file_name": "audio.mp3",
  "file_size": 2345569434,
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "self_link": "https://movida.bebanjo.net/api/audio_tracks/17",
  "file_link": "https://wadus.bebanjo.net/audio.mp3",
  "metadata_link": "https://movida.bebanjo.net/api/audio_tracks/17/metadata",
  "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
}

Updating an audio track

As our introduction to REST APIs guide suggests, you can update an audio track issuing a PUT request to a given audio track URI:

$ cat audio_track_update.xml

$ cat audio_track_update.json

<audio-track>
  <language>spa</language>
  <original-version>true</original-version>
  <channels>Stereo</channels>
</audio-track>

{
  "language": "spa",
  "original_version": "true",
  "channels": "Stereo"
}

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<audio-track>
  <id type="integer">17</id>
  <language>spa</language>
  <original-version type="boolean">true</original-version>
  <encoding>WMA9</encoding>
  <mix-type>Dolby Digital</mix-type>
  <channels>Stereo</channels>
  <audio-description nil="true"/>
  <file-name>audio.mp3</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1bbc4c41ea7c9d3a7dc1509727f698b7</file-md5>
  <link rel="self" href="https://www.example.com/api/audio_tracks/17"/>
  <link rel="file" href="https://wadus.bebanjo.net/audio.mp3"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/audio_tracks/17/metadata"/>
  <link rel="rendition" href="https://movida.bebanjo.net/api/renditions/39"/>
</audio-track>

{
  "resource_type": "audio_track",
  "id": 17,
  "language": "spa",
  "original_version": true,
  "encoding": "WMA9",
  "mix_type": "Dolby Digital",
  "channels": "Stereo",
  "audio_description": null,
  "file_name": "audio.mp3",
  "file_size": 2345569434,
  "file_md5": "1bbc4c41ea7c9d3a7dc1509727f698b7",
  "self_link": "https://movida.bebanjo.net/api/audio_tracks/17",
  "file_link": "https://wadus.bebanjo.net/audio.mp3",
  "metadata_link": "https://movida.bebanjo.net/api/audio_tracks/17/metadata",
  "rendition_link": "https://movida.bebanjo.net/api/renditions/39"
}

Deleting an audio track

You can also delete an audio track using DELETE request to each audio track URI:

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

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

The DELETE request doesn’t return anything, as that audio track is now gone.

Note: Deleting an audio track won’t have any side-effect on the parent rendition.

File Name Validation

Note that the Mediagenix On-Demand API validates the file name for audio_track 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.