Subtitles

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

The CONNECT Player SDK includes built-in support for subtitles. 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.

JS

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

Tracks are enabled and disabled 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:

JS

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 shown

Enabling Text track display using preferred language

You can configure the subtitle/close-captions/active-description language preference for DASH content for the player once the player instance is created but before setting the source for the player playback. The player obtains the track information after parsing the manifest file and then activates the text track in the display if the show mode is configured to display and any one of the available tracks is matched to the configured text language preference.

The subtitle show mode is configured to the player using the autoShowText configuration with a value below.

Show Mode	Value	Type	Description
`NEVER`	0	number	Never show text automatically on startup.
`ALWAYS`	1	number	Always show text automatically on startup.
`IF_PREFERRED_TEXT_LANGUAGE`	2	number	Show text automatically on startup if it matches the preferred text language.
`IF_SUBTITLES_MAY_BE_NEEDED`	3	number	Show text automatically on startup if we think that subtitles may be needed. This is specifically if the selected text matches the preferred text language AND is different from the initial audio language. (Example: You prefer English, but the audio is only available in French, so English subtitles should be enabled by default.) This is the default setting.

You can configure the text language for the player using the configuration preferredTextLanguage with a value in the form of ISO-639-1 language code (two-letter language code with the optional region subtag) as specified at http://www.iso.org/iso/home/standards/language_codes.htm.

Example code for setting the track show mode and track language preference.

JS

playerInstance.otvtoolkit().configure("autoShowText", 2); //To set the player to enable the text track based on the preferred language
playerInstance.otvtoolkit().configure("preferredTextLanguage", "es"); // Enable the Spanish text track if available
playerInstance.otvtoolkit().configure("preferredTextLanguage", "en-UK"); // Enable the English(United Kingdom) text track if available