A Note on "Remote" Text Tracks

Video.js refers to so-called "remote" text tracks. This is a convenient term for tracks that have an associated <track> element rather than those that do not.

Either can be created programmatically, but only remote text tracks can be removed from a player. For that reason, we recommend only using remote text tracks.

Creating the Text File

Timed text requires a text file in WebVTT format. This format defines a list of "cues" that have a start time, an end time, and text to display. Microsoft has a builder that can help you get started on the file.

Note: When creating captions, there are additional caption formatting techniques to make captions more meaningful, like brackets around sound effects (e.g. [ birds chirping ]).

For a more in depth style guide for captioning, see the Captioning Key, but keep in mind not all features are supported by WebVTT or (more likely) the Video.js WebVTT implementation.

Adding Text Tracks to Video.js

Once you have your WebVTT files created, you can add them to your video element using the track tag. Similar to source elements, track elements should be added as children of the video element:

track Attributes

kind

"subtitles" (default): Translations of the dialogue in the video for when audio is available but not understood. Subtitles are shown over the video.

"captions": Transcription of the dialogue, sound effects, musical cues, and other audio information for viewer who are deaf/hard of hearing, or the video is muted. Captions are also shown over the video.

"chapters": Chapter titles that are used to create navigation within the video. Typically, these are in the form of a list of chapters that the viewer can use to navigate the video.

"descriptions": Text descriptions of the action in the content for when the video portion isn't available or because the viewer is blind or not using a screen. Descriptions are read by a screen reader or turned into a separate audio track.

"metadata": Tracks that have data meant for JavaScript to parse and do something with. These aren't shown to the user.

Text Tracks from Another Domain

Because Video.js loads the text track file via JavaScript, the same-origin policy applies. If you'd like to have a player served from one domain, but the text track served from another, you'll need to enable CORS on the server that is serving your text tracks.

In addition to enabling CORS, you will need to add the crossorigin attribute to the video element itself. This attribute has two possible values "anonymous" and "use-credentials". Most users will want to use "anonymous" with cross-origin tracks:

One thing to be aware of is that the video files themselves will also need CORS headers. This is because some browsers apply the crossorigin attribute to the video source itself and not just the tracks. This is considered a security concern by the spec.

Working with Text Tracks

Showing Tracks Programmatically

Certain use cases call for turning captions on and off programmatically rather than forcing the user to do so themselves. This can be easily achieved by modifying the mode property of the text tracks.

The mode can be one of three values "disabled", "hidden", and "showing". When a text track's mode is "disabled", the track does not show on screen as the video is playing.

When the mode is set to "showing", the track is visible to the viewer and updates while the video is playing.

Listen for a Cue Becoming Active

One of the supported values for mode is "hidden". This mode means that the track will update as the video is playing, but it won't be visible to the viewer. This is most useful for tracks where kind="metadata".

A common use case for metadata text tracks is to use them to trigger behaviors when their cues become active. For this purpose, tracks emit a "cuechange" event.

Emulated Text Tracks

By default, Video.js will use native text tracks and fall back to emulated text tracks if the native functionality is broken, incomplete, or non-existent. The Flash tech will always use the emulated text track functionality.

Text Track Precedence

In general, "descriptions" tracks are of lower precedence than "captions" and "subtitles". What this mean for developers using Video.js?

If you are using the default attribute, Video.js will choose the first track that is marked as default and turn it on. If there are multiple tracks marked default, it will turn on the first "captions" or "subtitles" track before any "descriptions" tracks.

This only applied to the emulated text track support, native text tracks behavior will change depending on the browser.

If a track is selected from the menu, Video.js will turn off all the other tracks of the same kind. While this suggests Video.js supports both "subtitles" and "captions" being turned on simultaneously, this is currently not the case; Video.js only supports one track being displayed at a time.

This means that for emulated text tracks, Video.js will display the first enabled "subtitles" or "captions" track.

When native text tracks are supported, other tracks of the same kind will still be disabled, but it is possible that multiple text tracks are shown.

If a "descriptions" track is selected and subsequently a "subtitles" or "captions" track is selected, the "descriptions" track is disabled and its menu button is also disabled.