Subtitles and captions

MKPlayer supports in-stream subtitles and captions from HLS and DASH manifests, as well as external subtitle tracks you add programmatically. You manage tracks through the player.subtitles API.

Subtitles have a kind of "subtitle". Captions (closed captions) have a kind of "caption". The API handles both the same way.

Prerequisites

You have an initialised MKPlayer instance with a source loaded. See Loading and playing content.

Enable and disable tracks

After a source loads, list available subtitle tracks and enable the one you want:

// List all available subtitle and caption tracks
const tracks = player.subtitles.list();
console.log(tracks);
// Enable a track by its ID
// By default, enabling one track disables all others
player.subtitles.enable("track-id");
// Enable a track without disabling others
player.subtitles.enable("track-id", false);
// Disable a track
player.subtitles.disable("track-id");

Each track in the list is an MKSubtitleTrack object with the following properties:

Add external subtitle tracks

You can add external subtitle tracks programmatically. Pass an MKSubtitleTrack object to player.subtitles.add():

player.subtitles.add({
  id: "en-subs",
  label: "English",
  lang: "en",
  kind: "subtitle",
  url: "https://my-cdn.com/subtitles/en.vtt"
});

Alternatively, include external tracks in the source configuration before calling player.load():

const sourceConfig = {
  title: "My Stream",
  hls: "https://my-cdn.com/mysource/hls/index.m3u8",
  subtitleTracks: [
    {
      id: "en-subs",
      label: "English",
      lang: "en",
      kind: "subtitle",
      url: "https://my-cdn.com/subtitles/en.vtt"
    }
  ]
};

Remove a track

player.subtitles.remove("track-id");

If the track is currently enabled, it is disabled before removal.

Style subtitles

You can change subtitle appearance at runtime using player.setSubtitleStyle(). Pass a style options object with any combination of the supported properties:

player.setSubtitleStyle({
  fontSize: "50",
  fontStyle: "normal",
  fontFamily: "normal",
  fontColor: "white",
  fontOpacity: "75",
  backgroundColor: "black"
});

Supported style options:

Subtitle overlay

The player renders subtitles using a built-in overlay by default (enableSubtitleOverlay: true). To handle subtitle rendering yourself, disable the overlay and listen for cue events:

const playerConfig = {
  key: "YOUR_PLAYER_LICENSE_KEY",
  enableSubtitleOverlay: false
};

Then subscribe to cue events to receive subtitle text as it becomes active:

player.on(mkplayer.MKPlayerEvent.CueEnter, (event) => {
  // event.html contains the cue content
  console.log("Subtitle cue entered: ", event.html);
});
player.on(mkplayer.MKPlayerEvent.CueExit, (event) => {
  console.log("Subtitle cue exited");
});

Note: the subtitle overlay is automatically disabled when the built-in UI (ui: true) is enabled. To use the overlay, keep ui disabled.