Documentation
Community & SupportDashboard
Start typing to search…

Track insertion transform

Perform side-loading of subtitle files or other type of tracks to an existing VOD asset.

Track insertion transforms are created using the transform endpoint in MK.IO API.

☝️

Track side-loading is only available for MP4 content and requires a WebVTT file (.vtt) provided as input to the job.

Track insertion preset must use the #MediaKind.TrackInserterPreset value for @data.type attribute.


☝️

If the manifest has been played recently before inserting a subtitle track, there may be a delay of a couple of minutes before the manifest is served with the new subtitles, due to caching.

Configuration parameters

The following table lists the configuration parameters for the VTT side-loading:

Parameter

Description

@odata.type

Only subtitle track addition is supported for now and the following value must be used: #MediaKind.TextTrack

trackName

The name of the track as it will appear in the manifest..

displayName

The display name of the track on a video player.
In HLS, this maps to the NAME attribute of EXT-X-MEDIA.

hlsSettings

The HLS specific setting for the track.
The attributes for this object are described in a separate table.

languageCode

The language code for the track. The value is an RFC5646 language code.

playerVisibility

When playerVisibilityis set to Visible, the track will be present in the DASH manifest or HLS playlist when requested by a client.
When the playerVisibilityis set to Hidden, the track will not be available to the client.
The default value is 'Visible'."

HLS Specific Settings

Parameter

Description

characteristics

The characteristics for the HLS setting.
For subtitles, a comma separated string of public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound and public.easy-to-read can be provided.

default

A boolean indicating whether this track should be marked as a default track in the HLS playlist.
If value is 1, the HLS playlist will contain a DEFAULT=YES attribute.

forced

A boolean indicating whether this track should be marked as a essential for playback in the HLS playlist.
If value is 1, the HLS playlist will contain a FORCED=YES attribute.

Transform example

Below is a sample transform that illustrates how to use these parameters.

Once the transform is in place, it can be used to create a job on a given VOD asset.

Add a subtitle track to a VOD asset

Below is a sample transform that will add an English hearing-impaired VTT subtitle track.

curl --request PUT \
     --url https://api.io.mediakind.com/api/ams/project_name/transforms/transform_name \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer bearer-token' \
     --data '
{
  "properties": {
    "outputs": [
      {
        "preset": {
          "@odata.type": "#MediaKind.TrackInserterPreset",
          "tracks": [ 
            {
                "@odata.type": "#MediaKind.TextTrack",
                "trackName": "subtitle_en_US",
                "displayName": "eng (hearing-impaired)",
                "hlsSettings": {
                    "characteristics": "public.accessibility.describes-music-and-sound"
                },
                "languageCode": "en-US"
            }
          ]
        }
      }
    ]
  }
}
'

Updated about 2 months ago