Manage alternate audio tracks

The alternate audio tracks feature allows you to enable your viewers to choose from a variety of audio tracks for the video resource being watched:

• Dialogue translations
• Changing background music in a fitness or training video
• Commentary tracks
• Descriptive audio for visually impaired viewers

🚧

Alternate audio tracks are only supported in HLS delivery. They are not supported in progressive MP4s served out of JW Stream.

Additionally, ensure that your audio files are the same duration as the video. If the duration of an audio file and the video do not match, playback errors can occur.

Requirements

• Media ID of a video hosted in your JW Player account
• Property ID associated with the media ID (available in the Properties section of your JW Player Dashboard)
• JW API v2 secret (available in the API Credentials section of your JW Player Dashboard)
• Audio file (.aac, .m4a, mp3) on a local machine

🚧

The running length of an alternate audio track may not exceed 24 hours.

Unsupported Features

• DRM-enabled properties
• Renaming the default audio track
• Setting an alternate audio track as the default track for a video. The audio track that is in the uploaded video asset will always be the default for that video.

Add an alternate audio track

You can upload an alternate audio track using one of the following methods explained in the following table and sections.

💡

You can also add alternate audio tracks from your JW Player dashboard.

Direct Single Upload

The direct upload method is the simplest way to get a locally available, smaller (<100MB) file ingested into JW Player's platform. JW Player uses CDN acceleration and parallelized uploading that can decrease the time required to upload the file.

The process involves directly uploading the file to a provided link. Because of this, the direct upload method is not resumable, and network errors will require starting over.

1. Make a POST /v2/sites/{property_id}/media/{media_id}/originals call to upload the new audio track (original) and associate it with a specific video resource. Within the JSON body, set upload.method to direct and define the metadata of the original.
   
   Use the following example and table to create your API call.

curl -X POST https://api.jwplayer.com/v2/sites/{property_id}/media/{media_id}/originals \
 -H 'Authorization: Bearer {v2_api_secret}' \
 -H 'Content-Type: application/json' \
 -d '{"upload":{"method":"direct"},"metadata":{"name":"My New Original","language":"English","language_code":"en"}}'

The API call returns a response with the upload_link location.

{
    "container_format": null,
    "created": "2021-03-17T18:00:27+00:00",
    "error_message": null,
    "id": "M6UowlzH",
    "last_modified": "2021-03-17T18:00:27+00:00",
    "md5": null,
    "metadata": {
        "language": "English",
        "language_code": "en",
        "name": null,
        "type": null
    },
    "relationships": {},
    "schema": null,
    "size": null,
    "status": "created",
    "type": "original",
    "upload_link": "https://jwplayer-upload.s3-accelerate.amazonaws.com/qwer4321?AWSAccessKeyId=&Signature=%3D&Expires=1617647941"
}

2. Upload the local original to the upload_link location.

curl --upload-file {path_to_file} "{upload_link}"

💡

To confirm that the audio files have been uploaded, make a GET request to /v2/sites/{property_id}/media/{media_id}/originals. Uploaded files will have a processing status.

Multipart Resumable Upload

When you have a file that is >100 MB in size that you need to upload from your local machine, you should use this approach.

This method has several advantages:

• Speed: CDN acceleration and parallelized uploading can decrease the time required to upload.
• Resumability: Network failures don't require starting over. Uploading can be paused.
• Measurability: Upload progress can be more easily measured.

1. Make a POST /v2/sites/{property_id}/media/{media_id}/originals call to upload the new audio track (original) and associate it with a specific video resource. Within the JSON body, set upload.method to multipart and define the metadata of the original.

Use the following example and table to create your API call.

curl -X POST https://api.jwplayer.com/v2/sites/{property_id}/media/{media_id}/originals \
 -H 'Authorization: Bearer {v2_api_secret}' \
 -H 'Content-Type: application/json' \
 -d '{"upload":{"method":"multipart"},"metadata":{"name":"My New Original","language":"English","language_code":"en"}}'

The API call returns a response with the upload_id and upload_token. These fields will be used to interact with the Upload API.

{
    "container_format": null,
    "created": "2021-04-05T17:39:01+00:00",
    "error_message": null,
    "id": "rqnFY4e0",
    "last_modified": "2021-04-05T17:39:01+00:00",
    "md5": null,
    "metadata": {
        "language": "English",
        "language_code": "en",
        "name": "My Original",
        "type": null
    },
    "relationships": {},
    "schema": null,
    "size": null,
    "status": "created",
    "type": "original",
    "upload_id": "zxcv1234",
    "upload_token": "abcdefhijk.123456789.kjihfedcba"
}

2. Determine the number of parts into which the file should be split and the size of each part. For example, if a file is 500MB, you could split the file into 5 MB parts. This means that your part count will be 100 parts. You should choose your part size to optimize either for resumability (smaller part sizes) or reducing network overhead (larger part sizes).
   
   The minimum size for a part is 5 MB (with the exception of the last part). The maximum number of possible parts is 10,000.

3. Make a GET /v1/uploads/{upload_id}/parts call to get a list of upload parts.
   
   You can copy the following sample. Be sure to replace the {upload_id} and {upload_token} placeholders with the upload_id and upload_token that you received from API response in step 1. Also, set page_length to the part count. In the example, 100 is used. The API call will return a response that lists 100 parts. Each part will have an upload_link location.

curl 'https://api.jwplayer.com/v2/uploads/{upload_id}/parts?page=1&page_length=100' \
 -H 'Authorization: Bearer {upload_token}' \
 -H 'Content-Type: application/json'

4. Upload the bytes of the local media file part to the upload_link location. Be sure to replace the PATH_TO_YOUR_VIDEO with the actual path to the file. Use the following table to define the bs, count, and skip parameters within your request.

Below is an example of reading 5 MB parts at a time and uploading each part to its respective upload_link.

dd if=~/{path_to_your_video}.mp4 bs=5M count=1 skip=0 | curl \
  -XPUT -H "Content-Type:" \
  --data-binary @- \
  "{upload_link_1}"

dd if=~/{path_to_your_video}.mp4 bs=5M count=1 skip=1 | curl \
  -XPUT -H "Content-Type:" \
  --data-binary @- \
  "{upload_link_2}"

...

dd if=~/{path_to_your_video}.mp4 bs=5M count=1 skip=99 | curl \
  -XPUT -H "Content-Type:" \
  --data-binary @- \
  "{upload_link_100}"

5. After all parts have been uploaded, make a PUT /v1/uploads/{upload_id}/complete call. This signals to JW Player that all parts have been uploaded.

curl -X PUT \
  -H "Authorization: Bearer {upload_token}" \
  -H "Content-Type: application/json" \
  "https://api.jwplayer.com/v2/uploads/{upload_id}/complete"

💡

Subsequent calls to GET /v1/uploads/{upload_id}/parts will return both completed and uncompleted parts.

Completed parts will have the etag field set to an MD5 hash of the uploaded part and upload_link field will no longer be present. Counting the number of completed parts is a way of checking the progress of an upload.

Delete or replace an audio track

If you need to replace an audio track that you have added, you must delete the existing audio file before you can upload a new version of the audio track.

1. Make a DELETE /v2/sites/{property_id}/media/{media_id}/originals/{original_id} call to remove the audio file that you want to replace from the associated video file.

curl -X DELETE https://api.jwplayer.com/v2/sites/{property_id}/media/{media_id}/originals/{original_id} \
 -H 'Authorization: Bearer {v2_api_secret}' \
 -H 'Content-Type: application/json'

2. Follow the steps to Add an alternate audio track.