Documentation
Community & SupportDashboard

Track insertion transform for a VOD asset

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

Suggest Edits

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 back before inserting a subtitle track, there will be a delay of up to 60s before the manifest will contain the subtitles, due to cache settings.

Configuration parameters

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

ParameterDescription
@odata.typeOnly subtitle track addition is supported for now and the following value must be used: #MediaKind.TextTrack
trackNameThe name of the track as it will appear in the manifest..
displayNameThe display name of the track on a video player.
In HLS, this maps to the NAME attribute of EXT-X-MEDIA.
hlsSettingsThe HLS specific setting for the track.
The attributes for this object are described in a separate table.
languageCodeThe language code for the track. The value is an RFC5646 language code.
playerVisibilityWhen 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

ParameterDescription
characteristicsThe 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.
defaultA 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.
forcedA 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 1 day ago