TextTrack
The TextTrack
interface of the WebVTT API represents a text track associated with a media element.
An object of this type owns the list of VTTCue
objects that will be displayed over the video at various points.
TextTrack
objects can be added to a HTMLVideoElement
or HTMLAudioElement
element using the HTMLMediaElement.addTrack()
method, which has the same effect as adding text tracks declaratively using <track>
elements inside a <video>
or <audio>
element.
The TextTrack
objects are stored in a TextTrackList
, which can be retrieved using the HTMLMediaElement.textTracks
property.
Instance properties
This interface also inherits properties from EventTarget
.
TextTrack.activeCues
Read only-
A
TextTrackCueList
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.cues
Read only-
A
TextTrackCueList
which contains all of the track's cues. TextTrack.id
Read 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.inBandMetadataTrackDispatchType
Read only-
Returns a string which indicates the track's in-band metadata track dispatch type.
TextTrack.kind
Read only-
Returns a string indicating what kind of text track the
TextTrack
describes. It must be one of the permitted values. TextTrack.label
Read 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.language
Read only-
A string which 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 HTML
lang
attribute. For example, this can be"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 is
disabled
, unless the<track>
element'sdefault
boolean attribute is set totrue
— in which case the default mode isshowing
.
Instance 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
TextTrackCue
object) to the track's list of cues. TextTrack.removeCue()
-
Removes a cue (specified as a
TextTrackCue
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 the
oncuechange
property.
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
BCD tables only load in the browser