Subtitles

To test this feature and view the example code, please see the  Browsers SDK 1 Example Code Quick Start guide.

The browser SDK includes built-in support for the following subtitle formats:

• EBU-TT-D-subtitle-(Fragmented)
• IMSC1 support (ttml)
• SMPTE-TT-TTML-subtitle-xml-text
• SMPTE-TT-TTML-subtitle-xml-image
• SMPTE-TT-IMS-image-fragmented-subtitle
• SMPTE-TT-Multiple-subtitle-xml-based
• SMPTE-TT-Multiple-subtitle-ttml-based
• SMPTE-TT-TTML-Segmented-Subtitles-VoD
• SMPTE-TT-TTML-Segmented-Subtitles-live
• SMPTE-TT-segmented-snaking-subtitle

Where supported text or caption tracks are present for a chosen piece of content, they will be added automatically to the player instance. If the player control bar is being used, then selection and deselection will be available via the text-selection icon in the control bar.

Support has been verified for the following formats on Windows/Mac playing on Chrome, Edge (Chromium), and Firefox. Support for connected TV (Tizen and WebOS) has also been verified.

Taking control

Several events and API calls enable the application to take control of subtitle tracks. This document shows how to add, remove, activate and disable a text track. For more information on how to work with text tracks, see https://html.spec.whatwg.org/multipage/media.html#timed-text-tracks.

The following examples show how to work with remote text tracks, (tracks that have an associated track element as opposed to those that do not). The differences are minimal, however; remote text tracks can be removed from the player, whereas normally added text tracks have no remove API and cannot be removed.

Getting the list of text tracks

The player assumes an instance of otvplayer.

• player.textTracks(); returns the whole TextTrackList, including any remote text tracks, or:
• player.remoteTextTracks(); returns the remote TextTrackList, see https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList

Adding a track

• player.addTextTrack(TextTrack); adds a Text Track to the TextTrackList which cannot be removed.
• player.addRemoteTextTrack(TextTrack); adds a remote Text Track to the remote TextTrackList, see https://developer.mozilla.org/en-US/docs/Web/API/TextTrack

Removing a track

• player.removeTextTracks(); removes a remote TextTrack

Keeping track of the changes

Three callbacks: onaddtrack, onremovetrack and onchange are provided on the TextTrackList to help keep track of when text tracks are added or removed, and there is a change event that can be listened for.

let myTextTracks = player.addTextTrack(TextTrack);
myTextTracks.onaddtrack = updateTrackCount;
myTextTracks.onremovetrack = updateTrackCount;
myTextTracks.onchange = updateTrackCount;
function updateTrackCount(event) {
  trackCount = myTextTracks.length;
  // or however you want to handle this
}
myTextTracks.addEventListener('change', (event) => {
    console.log(`'${event.type}' event fired`);
});

Enabling and disabling a text track

Enabling and disabling tracks is done by switching the value of the mode property on a Track object to the desired value. The allowed values are textTrack.mode = "disabled"  | "hidden"  | "showing". For more information on the mode options and their usage, see https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/mode#Text_track_mode_constants); for example:

let myTextTracks = player.TextTracks(); // assume 2 tracks, first is selected
let track = myTextTracks[1];
track.mode = "showing"; // This will show the second, hide the first, but not disable the first.
track.mode = "disabled"; // this would disable the active subtitle, and the first would show again.
myTextTracks[0].mode = "disabled"; // This would disable the first, and no subtitles would be show