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: `<AdaptationSet contentType="text" group="2" lang="en" mimeType="application/mp4" segmentAlignment="true">` 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: `<div xml:lang="en">`
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.mp4Learn 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: `<AdaptationSet contentType="text" group="2" lang="en" mimeType="application/mp4" segmentAlignment="true">` 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: `<div xml:lang="en">`
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. 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 API Auth for V2 APIs (see below), 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
}