## HTML Audio/Video DOM addTextTrack() Method
The `addTextTrack()` method is a built-in HTML5 DOM method used to programmatically create and return a new `TextTrack` object. This new track is automatically appended to the media element's list of text tracks (such as subtitles, captions, or descriptions).
---
## Definition and Usage
The `addTextTrack()` method allows developers to dynamically add text tracks to an `
` or `` element directly via JavaScript, without needing to declare a `` element in the static HTML markup.
Once the `TextTrack` object is created, you can dynamically add cues (using `addCue()`) to display text at specific timestamps during media playback.
---
## Syntax
```javascript
mediaElement.addTextTrack(kind, label, language)
```
### Parameter Values
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `kind` | String | **Required.** Specifies the type of text track. Allowed values include:`"subtitles"`: Transcription or translation of the dialogue, suitable for when the sound is available but not understood. `"captions"`: Transcription or translation of dialogue, sound effects, and other relevant audio information, suitable for when the sound is unavailable or muted. `"descriptions"`: Textual descriptions of the video's visual actions, suitable for audio description. `"chapters"`: Chapter titles, intended to help the user navigate the media resource. `"metadata"`: Track intended for use by scripts. Not visible to the user. |
| `label` | String | **Optional.** A user-readable title for the text track (e.g., "English CC", "Director's Commentary"). This is typically displayed by the browser in its track selection menu. |
| `language` | String | **Optional.** A two-letter language code specifying the language of the text track (e.g., `"en"`, `"zh"`, `"es"`). |
### Return Value
| Type | Description |
| :--- | :--- |
| `TextTrack` Object | Represents the newly created text track. |
---
## Code Example
The following example demonstrates how to add a new text track to a video element and programmatically insert a subtitle cue using JavaScript:
```javascript
// Get the video element from the DOM
const myVid = document.getElementById("myVideo");
// Add a new captions track in English
const textTrack = myVid.addTextTrack("captions", "English Captions", "en");
// Make the track visible
textTrack.mode = "showing";
// Add a cue to the track: display "Hello World" from 1.0 second to 4.0 seconds
// Note: Modern browsers use the VTTCue constructor
if (typeof VTTCue !== 'undefined') {
textTrack.addCue(new VTTCue(1.0, 4.0, "Hello World"));
} else if (typeof TextTrackCue !== 'undefined') {
// Fallback for older specifications
textTrack.addCue(new TextTrackCue(1.0, 4.0, "Hello World"));
}
```
---
## Browser Compatibility & Considerations
* **Standard Compliance:** While early implementations of the HTML5 track API had limited or inconsistent support across browsers, modern evergreen browsers (Chrome, Firefox, Safari, Edge) fully support `addTextTrack()` and the standard `VTTCue` constructor.
* **`TextTrackCue` vs `VTTCue`:** The original specification defined `TextTrackCue`, but modern browsers have deprecated direct instantiation of `TextTrackCue` in favor of `VTTCue` (WebVTT Cue). Always check for `VTTCue` support when dynamically adding cues.
* **Track Visibility:** By default, a newly added text track may have its `mode` set to `"disabled"`. To make the cues visible on the video player, you must explicitly set the track's mode to `"showing"` (or `"hidden"` if you want the cues to trigger events without being rendered on screen):
```javascript
textTrack.mode = "showing";
```