API

Text Tracks

An overview of using and configuring text tracks (captions/subtitles).

The Loading Text Tracks guide covers how to initialize tracks and supported formats/kinds.

The read-only textTracks property on the player returns a TextTrackList object that contains TextTrack objects. Keep in mind the mentioned objects are custom implementations and not the browser’s native classes.

The returned list is live; that is, as tracks are added to and removed from the player, the list’s contents change dynamically. Once you have a reference to the list, you can monitor it for changes to detect when new tracks are added or existing ones are removed by listening to list events.

The TextTrackList object is an EventTarget which dispatches the following events:

• add: Fired when a text track has been added to the list.
• remove: Fired when a text track has been removed from the list.
• mode-change: Fired when the mode of any text track has changed.

Text tracks can be dynamically added and removed like so:

You can also create tracks and add them programtically like so:

Text tracks can be removed programtically like so:

All text tracks can be removed by calling clear():

The mode property of a text track accepts the following values:

• showing: Track will load, receive cue updates, and is visible on-screen.
• hidden: Track will load, receive cue updates, but is not visible on-screen.
• disabled: Track will not load and it will not receive cue updates.

Only one track per kind can have a mode of showing. Other tracks of the same kind that are specifically showing will have their mode set to disabled on change.

The TextTrack object is an EventTarget which dispatches the following events:

• load-start: Fired when the track begins loading.
• load: Fired when the track has finished loading and parsing.
• error: Fired when there is a critical error loading or parsing the track.
• add-cue: Fired when a new cue has been added.
• remove-cue: Fired when a cue has been removed.
• cue-change: Fired when the active cues has changed.
• mode-change: Fired when the mode has been changed.

The following text track related properties are available on the media store:

• textTracks: An array containing the current list of TextTrack objects.
• textTrack: The current captions/subtitles TextTrack object or null if none is showing.

The changeTextTrack method on the media remote can be used to dispatch media-text-track-change-request request events to update the current audio track like so:

The following text track related events are available on the player: