The TextTrack interface—part of the API for handling WebVTT (text tracks on media presentations)—describes and controls the text track associated with a particular <track> element.
TextTrack
Properties
This interface also inherits properties from EventTarget.
-
TextTrack.activeCuesRead only -
A
TextTrackCueListobject 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 -
A
TextTrackCueListwhich contains all of the track's cues. -
TextTrack.idRead only -
A
DOMStringwhich identifies the track, if it has one. If it doesn't have an ID, then this value is an empty string (""). If theTextTrackis associated with a<track>element, then the track's ID matches the element's ID. -
TextTrack.inBandMetadataTrackDispatchTypeRead only -
Returns a
DOMStringwhich indicates the track's in-band metadata track dispatch type. -
TextTrack.kindRead only -
Returns a
DOMStringindicating what kind of text track theTextTrackdescribes. It must be one of the permitted values. -
TextTrack.labelRead only -
A human-readable
DOMStringwhich 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
DOMStringwhich specifies the text language in which the text track's contents is written. The value must adhere to the format specified in RFC 5646: Tags for Identifying Languages (also known as BCP 47), just like the HTMLlangattribute. For example, this can be"en-US"for United States English or"pt-BR"for Brazilian Portuguese. -
TextTrack.mode -
A
DOMStringspecifying 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'sdefaultBoolean attribute is specified, in which case the default mode isstarted.
Methods
This interface also inherits methods from EventTarget.
Note: The TextTrackCue interface is an abstract class used as the parent for other cue interfaces such as VTTCue. Therefore, when adding or removing a cue you will be passing in one of the cue types that inherit from TextTrackCue.
-
TextTrack.addCue() -
Adds a cue (specified as a
TextTrackCueobject) to the track's list of cues. -
TextTrack.removeCue() -
Removes a cue (specified as a
TextTrackCueobject) 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 the
oncuechangeproperty.
Example
The following example adds a new TextTrack to a video, then sets it to display using TextTrack.mode.
let video = document.querySelector('video'); let track = video.addTextTrack("captions", "Captions", "en"); track.mode = "showing";
Specifications
| Specification |
|---|
| HTML Standard # texttrack |
Browser compatibility
| Desktop | Mobile | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
TextTrack |
23
|
12
|
31
Firefox versions before Firefox 50 didn't display captions when playing media without one or more video tracks being played.
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
activeCues |
23
|
12
|
31
Starting in Firefox 69, cues are no longer incorrectly loaded when the
TextTrack's
mode is
disabled; if that's the case, the returned list is empty.
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
addCue |
23
|
12
|
31
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
cuechange_event |
23
|
12
|
31
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
cues |
23
|
12
|
31
Starting in Firefox 69, cues are no longer incorrectly loaded when the
TextTrack's
mode is
disabled; if that's the case, the returned list is empty.
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
id |
33
|
12
|
31
|
No
|
20
|
7
|
4.4.3
|
33
|
31
|
20
|
7
|
2.0
|
inBandMetadataTrackDispatchType |
No
See
bug 754093.
|
12-79
|
31
|
No
|
No
See
bug 754093.
|
7
|
No
See
bug 754093.
|
No
See
bug 754093.
|
31
|
No
See
bug 754093.
|
7
|
No
See
bug 754093.
|
kind |
23
|
12
|
31
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
label |
23
|
12
|
31
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
language |
23
|
12
|
31
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
mode |
23
|
12
|
31
Before Firefox 52, using JavaScript to change the mode of a text track that's part of a media element would send one change event to the element's textTracks TextTrackList for each change, even if mutliple changes are made in a single pass through the Firefox event loop. Starting in Firefox 52, these changes are reflected by a single event.
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
removeCue |
23
|
12
|
31
|
10
|
≤12.1
|
6
|
4.4
|
25
|
31
|
≤12.1
|
7
|
1.5
|
sourceBuffer |
No
|
No
|
No
|
No
|
No
|
8
|
No
|
No
|
No
|
No
|
13
Exposed in Mobile Safari on iPad but not on iPhone.
|
No
|
See also
© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/TextTrack
