subtitles.md

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:

Property	Type	Description
`id`	`string`	Track identifier used to enable, disable, or remove the track.
`label`	`string`	Display name shown to the user.
`lang`	`string`	Language of the track.
`kind`	`string`	Either "subtitle" or "caption".
`enabled`	`boolean`	Whether the track is currently active.
`forced`	`boolean`	If `true`, the player automatically selects this track to match the active audio language.
`url`	`string`	URL to the subtitle file, for external tracks.

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:

Property	Supported values
`fontSize`	"1" to "100"
`fontStyle`	"normal", "italic", "bold"
`fontFamily`	"Times New Roman", "fantasy", "cursive", "serif", "monospace", "Font Awesome 5 Free"
`fontColor`	"normal", "white", "black", "red", "green", "blue", "cyan", "yellow", "magenta"
`fontOpacity`	"0" to "100"
`backgroundColor`	"normal", "white", "black", "red", "green", "blue", "cyan", "yellow", "magenta"

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.