Track insertion transform

A track insertion transform adds a subtitle or audio track to an existing Video on Demand (VOD) asset. It also updates the asset’s client and server manifests with the new track.

Create track insertion transforms through the Media API. The MK.IO portal does not create this transform type.

Track side-loading is only available for MP4 content.

Set the preset’s @odata.type to #MediaKind.TrackInserterPreset. Each transform output can insert one text or audio track.

If clients requested the manifest shortly before insertion, caching can delay the updated manifest by a couple of minutes.

Configuration parameters

The following parameters configure the inserted track:

Parameter	Description
@odata.type	Use #MediaKind.TextTrack for a subtitle track or #MediaKind.AudioTrack for an audio track.
trackName	The name of the track as it will appear in the manifest.
hlsSettings	The HLS specific setting for the track. The attributes for this object are described in a separate table.
dashSettings	The DASH settings for the track. Only available for audio tracks. 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.
displayName	The display name of the track on a video player. In HLS, this maps to the NAME attribute of EXT-X-MEDIA.
playerVisibility	Set playerVisibility to Visible to include a text track in the DASH manifest or HLS playlist. Set it to Hidden to exclude the track. The default is Visible.

HLS specific settings

Parameter	Description
characteristics	The characteristics of the track as they appear in the HLS playlist. For subtitles, provide a comma-separated string containing public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound, public.easy-to-read, or public.machine-generated. For audio, provide a comma-separated string containing public.accessibility.describes-video or public.machine-generated.
default	Indicates whether the HLS playlist marks this track as the default. A value of 1 adds the DEFAULT=YES attribute.
forced	Indicates whether the HLS playlist marks this track as essential for playback. A value of 1 adds the FORCED=YES attribute.

DASH settings for audio tracks

Parameter	Description
role	The role of the audio track in the DASH manifest. Provide a comma-separated string containing main, alternate, supplementary, commentary, dub, or emergency.

Transform example

The following transform shows 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

The following transform adds an English VTT subtitle track for viewers who are deaf or hard of hearing.

curl --request PUT \
     --url https://app.mk.io/api/v1/projects/project_name/media/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"
            }
          ]
        }
      }
    ]
  }
}
'

Add an audio track to a VOD asset

The following transform adds a secondary audio track to VOD content.

curl --request PUT \
     --url https://app.mk.io/api/v1/projects/project_name/media/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.AudioTrack",
                "trackName": "ai-generated-fr-audio",
                "displayName": "fra",
                "languageCode": "fr-FR",
                "hlsSettings": {
                    "characteristics": "public.machine-generated"
                },
                "dashSettings": {
                    "role": "dub"
                }
            }
          ]
        }
      }
    ]
  }
}
'