Skip to navigation
ReferenceEncoding Transform Presets

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:

ParameterDescription
@odata.typeUse #MediaKind.TextTrack for a subtitle track or #MediaKind.AudioTrack for an audio track.
trackNameThe name of the track as it will appear in the manifest.
hlsSettingsThe HLS specific setting for the track. The attributes for this object are described in a separate table.
dashSettingsThe DASH settings for the track. Only available for audio tracks. The attributes for this object are described in a separate table.
languageCodeThe language code for the track. The value is an RFC5646 language code.
displayNameThe display name of the track on a video player. In HLS, this maps to the NAME attribute of EXT-X-MEDIA.
playerVisibilitySet 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

ParameterDescription
characteristicsThe 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.
defaultIndicates whether the HLS playlist marks this track as the default. A value of 1 adds the DEFAULT=YES attribute.
forcedIndicates 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

ParameterDescription
roleThe 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"
                }
            }
          ]
        }
      }
    ]
  }
}
'