Enhance your viewer's listening experience.
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.
Approach | File Location & Size | Additional Notes |
---|---|---|
Direct Single Upload | Location: Local machine Size: Best for uploading files that are 100 MB or less | Use when the media file is on the local machine The file should be small enough that retrying the entire file upload is not an issue. |
Multipart Resumable Upload | Location: Local machine Size: Best for uploading files that are 100MB-25GB | Use when the media file is on the local machine The file should be large enough that retrying the entire upload is an issue. The upload needs to be paused & resumed, or upload progress needs to be reliably reported. |
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.
- 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, setupload.method
todirect
and define themetadata
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"}}'
Body Parameter | Description |
---|---|
language string | Language dialect of the original resource When a name is not provided, language is used as the audio label. This is set to English as default on non-music type resources. |
language_code string | ISO 639-1 language code of the original resource This is set to en as default for non-music type resources. |
name string | Name of the original resource |
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"
}
- 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.
- 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, setupload.method
tomultipart
and define themetadata
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"}}'
Body Parameter | Description |
---|---|
language string | Language dialect of the original resource When a name is not provided, language is used as the audio label. This is set to English as default on non-music type resources. |
language_code string | ISO 639-1 language code of the original resource This is set to en as default for non-music type resources. |
name string | Name of the original resource |
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"
}
- 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.
- 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 theupload_id
andupload_token
that you received from API response in step 1. Also, setpage_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 anupload_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'
- Upload the bytes of the local media file part to the
upload_link
location. Be sure to replace thePATH_TO_YOUR_VIDEO
with the actual path to the file. Use the following table to define thebs
,count
, andskip
parameters within your request.
Parameter | Description |
---|---|
bs | Size of the part in megabytes (M) |
count | Number of parts This should always be 1. |
skip | Number of previous uploaded part to jump over |
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}"
- 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.
- 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'
- Follow the steps to Add an alternate audio track.