TheTextTrack interface of theWebVTT API represents a text track associated with a media element.

An object of this type owns the list ofVTTCue objects that will be displayed over the video at various points.

TextTrack objects can be added to aHTMLVideoElement orHTMLAudioElement element using theHTMLMediaElement.addTextTrack() method, which has the same effect as adding text tracks declaratively using<track> elements inside a<video> or<audio> element.TheTextTrack objects are stored in aTextTrackList, which can be retrieved using theHTMLMediaElement.textTracks property.

Instance properties

This interface also inherits properties fromEventTarget.

TextTrack.activeCuesRead only

ATextTrackCueList object listing the currently active set of text track cues. Track cues are active if the current playback position of the media is between the cues' start and end times. Thus, for displayed cues such as captions or subtitles, the active cues are currently being displayed.

TextTrack.cuesRead only

ATextTrackCueList which contains all of the track's cues.

TextTrack.idRead only

A string which identifies the track, if it has one. If it doesn't have an ID, then this value is an empty string (""). If theTextTrack is associated with a<track> element, then the track's ID matches the element's ID.

TextTrack.inBandMetadataTrackDispatchTypeRead only

Returns a string which indicates the track's in-band metadata track dispatch type.

TextTrack.kindRead only

Returns a string indicating what kind of text track theTextTrack describes. It must be one of the permitted values.

TextTrack.labelRead only

A human-readable string which contains the text track's label, if one is present; otherwise, this is an empty string (""), in which case a custom label may need to be generated by your code using other attributes of the track, if the track's label needs to be exposed to the user.

TextTrack.languageRead only

A string specifying the language in which the text track's contents is written. The value must be a validBCP 47 language tag, for example"en-US" for United States English or"pt-BR" for Brazilian Portuguese.

TextTrack.mode

A string specifying the track's current mode, which must be one of the permitted values. Changing this property's value changes the track's current mode to match. The default isdisabled, unless the<track> element'sdefault boolean attribute is set totrue — in which case the default mode isshowing.

sourceBufferRead only

TheSourceBuffer that created the track. Returns null if the track was not created by aSourceBuffer or theSourceBuffer has been removed from theMediaSource.sourceBuffers attribute of its parent media source.

Instance methods

This interface also inherits methods fromEventTarget.

TextTrack.addCue()

Adds a cue (specified as aTextTrackCue object) to the track's list of cues.

TextTrack.removeCue()

Removes a cue (specified as aTextTrackCue object) from the track's list of cues.

Events

cuechange

Fired when cues are entered and exited. A given text cue appears when the cue is entered and disappears when the cue is exited.Also available via theoncuechange property.

Example

The following example adds a newTextTrack to a video, then sets it to display usingTextTrack.mode.

let video = document.querySelector("video");let track = video.addTextTrack("captions", "Captions", "en");track.mode = "showing";

Specifications

Browser compatibility

See also

• WebVTT
• TextTrackCueList
• VTTCue
• <track>
• HTMLTrackElement