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.

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.
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	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 of the track as it will appear in the HLS playlist. For subtitles, a comma separated string of public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound, public.easy-to-read and public.machine-generatedcan be provided. For audio a comma separated string of public.accessibility.describes-video and public.machine-generatedcan 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.

DASH specific settings (for audio tracks only)

Parameter	Description
role	The role of the track as it will appear in the DASH manifest. For audio, a comma separated string of main, alternate, supplementary, commentary dub and emergency can be provided.

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://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

Below is a sample transform that will add a secondary audio to a 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"
                }
            }
          ]
        }
      }
    ]
  }
}
'