Adds a WebVTT track to an asset.
Key information:
-
Add up to 63 tracks to an asset.
You cannot add a track to an asset that is still being sliced.
-
Specify TTML data in the request or by providing a URL to it.
You may only add the first track from TTML data.
-
It takes approximately 30 seconds to add a track for a two hour asset.
Request
Request syntax:
/jobs/add_track_vtt
Request parameters:
The set of request parameters varies according to whether you plan on adding a single or multiple WebVTT tracks to an asset.
Single WebVTT track
Add a single WebVTT track to an asset by passing the following parameters through the msg parameter:
| Name | Data Type | Description | ||
|---|---|---|---|---|
| api_key | String | Amazon S3 (Private) Only Set this parameter if your TTML file is stored in a private bucket on Amazon S3. Identifies your AWS access key. | ||
| api_secret | String | Amazon S3 (Private) Only Set this parameter if your TTML file is stored in a private bucket on Amazon S3. Identifies your AWS secret access key. | ||
| asset Required | String | Identifies an asset by its asset ID or external ID. Asset ID Syntax: Asset ID External ID Syntax: ext:External ID ClosedWhere can I find an asset ID? 1. Navigate to the CMS library by clicking the Content tab. 2. Select the desired asset. 3. The asset ID corresponding to the asset selected in the previous step is listed under the GUID label. ClosedWhere can I find an asset's external ID? 1. Navigate to the CMS library by clicking the Content tab. 2. Select the desired asset. 3. The external ID corresponding to the asset selected in the previous step is listed under the External ID option. | ||
| default_position | String | Determines the default horizontal text alignment for captions and subtitles when the sidecar TTML file does not define a horizontal text alignment (i.e., tts:textAlign). Valid values are: left | center | right Default value: left |
| default_vertical | String | Determines the default vertical position for captions and subtitles when the sidecar TTML file does not define a vertical position (i.e., tts:origin). Valid values are: top | center | bottom Default value: top |
| desc | String | Overrides the description (e.g., English) for the track that will be added to the asset. | ||
| lang | String | Overrides the language (e.g., en) for the track that will be added to the asset. ClosedLearn how HLS and DASH handle language. HLS uses the track's desc as NAME and lang as LANGUAGE. #EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",DEFAULT=NO,FORCED=NO,URI="...", LANGUAGE="en",AUTOSELECT=YES,CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog" If a desc is not provided, then it sets NAME to Unknown. NAME="Unknown" DASH DASH identifies a track's language via lang: A video player may look up language codes to provide friendlier labels. Default value: The default value when language has not been defined within TTML data is: en Define language within TTML data via the following tag: | ||
| subtitle_absolute_time | Integer | Determines how timed text tracks (e.g., subtitles and closed captioning) are mapped to time. Valid values are: 0: Timed text tracks are mapped to a time that is relative to the timestamp defined within the X-TIMESTAMP-MAP header. 1: Timed text tracks are mapped using absolute time. This setting also removes the X-TIMESTAMP-MAP header from the WebVTT track. Default Behavior: If this setting is missing, then timed text tracks will be mapped according to whether other tracks within this asset use the X-TIMESTAMP-MAP header or absolute time. | ||
| ttml_data Required | String | You must specify either the ttml_url or ttml_data parameter. Contains Base64-encoded TTML data whose first track will be added to the asset. | ||
| ttml_url Required | String | You must specify either the ttml_url or ttml_data parameter. Identifies a URL that points to the TTML file whose first track will be added to the asset. Amazon S3 (Private) If your TTML file is stored in a private bucket on Amazon S3, then you must: Use the following syntax: s3://Bucket/Key Name Example: s3://mybucket/puppies.mp4 Learn more about AWS S3 format. Provide AWS credentials via the api_key and api_secret parameters. If your AWS S3 content is publicly accessible, then you should use an HTTP URL instead of an S3 URL. |
Multiple WebVTT tracks
Add multiple WebVTT tracks to an asset by passing the following parameters through the msg parameter:
| Name | Data Type | Description |
|---|---|---|
| asset Required | String | Identifies an asset by its asset ID or external ID. Asset ID Syntax: Asset ID External ID Syntax: ext:External ID ClosedWhere can I find an asset ID? 1. Navigate to the CMS library by clicking the Content tab. 2. Select the desired asset. 3. The asset ID corresponding to the asset selected in the previous step is listed under the GUID label. ClosedWhere can I find an asset's external ID? 1. Navigate to the CMS library by clicking the Content tab. 2. Select the desired asset. 3. The external ID corresponding to the asset selected in the previous step is listed under the External ID option. |
| source Required | List of dictionaries | Contains a list of WebVTT tracks that will be added to the asset. |
source List
The source list contains a dictionary for each WebVTT track that will be added to the asset. Describe each WebVTT track through the following properties:
| Name | Data Type | Description | ||
|---|---|---|---|---|
| api_key | String | Amazon S3 (Private) Only Set this parameter if your TTML file is stored in a private bucket on Amazon S3. Identifies your AWS access key. | ||
| api_secret | String | Amazon S3 (Private) Only Set this parameter if your TTML file is stored in a private bucket on Amazon S3. Identifies your AWS secret access key. | ||
| default_position | String | Determines the default horizontal text alignment for captions and subtitles when the sidecar TTML file does not define a horizontal text alignment (i.e., tts:textAlign). Valid values are: left | center | right Default value: left |
| default_vertical | String | Determines the default vertical position for captions and subtitles when the sidecar TTML file does not define a vertical position (i.e., tts:origin). Valid values are: top | center | bottom Default value: top |
| desc | String | Overrides the description (e.g., English) for the track that will be added to the asset. | ||
| lang | String | Overrides the language (e.g., en) for the track that will be added to the asset. ClosedLearn how HLS and DASH handle language. HLS uses the track's desc as NAME and lang as LANGUAGE. #EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",DEFAULT=NO,FORCED=NO,URI="...", LANGUAGE="en",AUTOSELECT=YES,CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog" If a desc is not provided, then it sets NAME to Unknown. NAME="Unknown" DASH DASH identifies a track's language via lang: A video player may look up language codes to provide friendlier labels. Default value: The default value when language has not been defined within TTML data is: en Define language within TTML data via the following tag: | ||
| subtitle_absolute_time | Integer | Determines how timed text tracks (e.g., subtitles and closed captioning) are mapped to time. Valid values are: 0: Timed text tracks are mapped to a time that is relative to the timestamp defined within the X-TIMESTAMP-MAP header. 1: Timed text tracks are mapped using absolute time. This setting also removes the X-TIMESTAMP-MAP header from the WebVTT track. Default Behavior: If this setting is missing, then timed text tracks will be mapped according to whether other tracks within this asset use the X-TIMESTAMP-MAP header or absolute time. | ||
| ttml_data Required | String | You must specify either the ttml_url or ttml_data parameter. Contains Base64-encoded TTML data whose first track will be added to the asset. | ||
| ttml_url Required | String | You must specify either the ttml_url or ttml_data parameter. Identifies a URL that points to the TTML file whose first track will be added to the asset. Amazon S3 (Private) If your TTML file is stored in a private bucket on Amazon S3, then you must: Use the following syntax: s3://Bucket/Key Name Example: s3://mybucket/puppies.mp4 Learn more about AWS S3 format. Provide AWS credentials via the api_key and api_secret parameters. If your AWS S3 content is publicly accessible, then you should use an HTTP URL instead of an S3 URL. |
Authentication
Pass a digital signature based off of msg.
Response
The response for a successful request contains the following parameter.
| Name | Data Type | Description |
|---|---|---|
| job | Dictionary | Describes the Cloud Slicer job that was created. |
Sample Request/Response
A sample request/response is provided below. The Call() function, which is imported from uplynk_api2_auth module, prepares the message body and digital signature.
from uplynk_api2_auth import Call
print(Call('/api2/cloudslicer/jobs/add_track_vtt', asset='ae01164a50a04847b5624485aae1aac3', ttml_url='https://cdn.example.com/resources/ttml/m_campaign_23.ttml))
{
'job': {
'last_error': '',
'args': {
'add_track_num': 0,
'old_ranges': {
'ranges': [[92416, -1, 92416], ... [164736, -1, 164736]],
'full_slice_samples': 196608,
'break_durations': {}
},
'ttml_data': None,
'write_dash': 2,
'ttml_url': 'https://cdn.example.com/resources/ttml/m_campaign_23.ttml'
},
'finished': 0,
'attempts': 0,
'source': {},
'state': 'waiting',
'asset': 'abb0000a6fe24c1f963e4dd51b37988e',
'last_start': 0,
'owner': 'cb233864a92b46a1a286cdd49b0a9bc8',
'progress': '',
'id': '7a04bd253c914eb496794f97a918da51'
},
'error': 0
}