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

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:

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

The subtitle/close captions/active description language preference can be configured to the player once it is created but before setting the playback source. The player comes to know the track information after parsing the manifest file and it can activate the text track in the display if the subtitle display mode is enabled and any one of the available tracks is matching with configured text language preference.

The subtitle display mode is configured with the configuration named autoShowText with values as given in the document https://shaka-player-demo.appspot.com/docs/api/shaka.config.AutoShowText.html

Name	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.

The Text language can be configured Shaka Player configuration named preferredTextLanguage with value in the form of ISO-639-1 language code(two-letter language code with the optional region subtag) as specified here http://www.iso.org/iso/home/standards/language_codes.htm

Example code for Setting the track display mode and track language preference:

JS

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