Replaces an asset's track.

Key information:

You cannot use this endpoint to add a track to an asset. Please use the Add WebVTT Track endpoint instead.
You cannot replace a track if the asset 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/replace_track_vtt

Request parameters:

The set of request parameters varies according to whether you plan on replacing a single or multiple WebVTT tracks.

Single WebVTT track

Replace a single WebVTT track 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: en TTML may override this default value 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 the track being replaced uses the X-TIMESTAMP-MAP header or absolute time.
track_num Required	Integer	Identifies the track that will be replaced using a zero-based index number.
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.

Replace multiple WebVTT tracks by passing the following parameters through the msg parameter:

Name	Data Type	Description
asset Required	String	Identifies an asset by its asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab.. 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.
source Required	List of dictionaries	Contains a list of WebVTT tracks that will replace existing tracks within the asset.

source List

The source list contains a dictionary for each WebVTT track that will replace an existing track within an 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: en TTML may override this default value 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 the track being replaced uses the X-TIMESTAMP-MAP header or absolute time.
track_num Required	Integer	Identifies the track that will be replaced using a zero-based index number.
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/replace_track_vtt', asset='ae01164a50a04847b5624485aae1aac3', ttml_url='https://cdn.example.com/resources/ttml/m_campaign_23.ttml', track_num=0))

{
	'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': '535a7bc35e69413f945348cdc3381ae8'
	},
	'error': 0
}