TextTrack
=========

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.

EventTarget

TextTrackInstance 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 the `TextTrack` 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's `default` boolean attribute is set to `true` — in which case the default mode is `showing`.

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`.


```js
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 with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebVTT
* `TextTrackCueList`
* `VTTCue`
* `<track>`
* `HTMLTrackElement`