## HTML Audio/Video DOM textTracks Property
The `textTracks` property is a powerful feature of the HTML5 Audio/Video DOM. It allows developers to access, inspect, and manipulate the text tracks (such as subtitles, captions, descriptions, chapters, or metadata) associated with a media element.
---
## Definition and Usage
The `textTracks` property returns a **`TextTrackList`** object.
* The **`TextTrackList`** represents all the available text tracks configured for the audio or video element (typically defined via `
` tags inside the `` or `` element).
* Each individual text track within this list is represented by a **`TextTrack`** object.
This property is essential for building custom media player controls, toggling subtitles dynamically, or reacting to metadata cues embedded in the media stream.
---
## Syntax
```javascript
let tracks = mediaElement.textTracks;
```
### Return Value
The property returns a `TextTrackList` object containing individual `TextTrack` objects.
#### 1. The `TextTrackList` Object
This list-like object contains the following properties and methods:
| Property / Method | Description |
| :--- | :--- |
| `length` | Returns the number of available text tracks in the media element. |
| `` | Accesses a specific `TextTrack` object by its index (starting at `0`). |
| `addEventListener()` | Allows listening to events on the track list, such as `change` (when a track's mode changes) or `addtrack` / `removetrack`. |
#### 2. The `TextTrack` Object
Each `TextTrack` object represents a single text track and exposes the following properties and methods:
| Property / Method | Type | Description |
| :--- | :--- | :--- |
| `kind` | String | The category of the text track. Possible values: `"subtitles"`, `"captions"`, `"descriptions"`, `"chapters"`, or `"metadata"`. |
| `label` | String | The user-readable title of the text track (e.g., "English SDH"). |
| `language` | String | The language of the text track (e.g., `"en"`, `"zh"`). |
| `mode` | String | The current state of the track. It can be read or written: `"disabled"`: The track is ignored by the browser. `"hidden"`: The track is active and events fire, but cues are not rendered on screen. `"showing"`: The track is active and visible.
Count Tracks
```
### Example 2: Toggle Subtitles Programmatically
You can loop through the `textTracks` list to find a specific language track and enable it while disabling others.
```javascript
function enableSpanishSubtitles() {
const video = document.getElementById("myVideo");
const tracks = video.textTracks;
for (let i = 0; i < tracks.length; i++) {
if (tracks.language === "es" && tracks.kind === "subtitles") {
tracks.mode = "showing"; // Make Spanish subtitles visible
} else {
tracks.mode = "disabled"; // Turn off other tracks
}
}
}
```
### Example 3: Dynamically Adding a Cue
You can programmatically add text cues to a track using JavaScript.
```javascript
const video = document.getElementById("myVideo");
// Get the first track
const track = video.textTracks;
// Ensure the track is active so cues are processed
track.mode = "showing";
// Create a new WebVTT cue: start at 1.0s, end at 5.0s, with text "Hello World"
const newCue = new VTTCue(1.0, 5.0, "Hello World");
// Add the cue to the track
track.addCue(newCue);
```
---
## Considerations & Best Practices
1. **Track Loading State**: When a page first loads, the `textTracks` list might be empty or incomplete if the track files (WebVTT) have not finished loading. Use the `onload` event of the `` element or listen to the `addtrack` event on the `textTracks` list to ensure tracks are ready before manipulating them.
2. **The `disabled` Mode Gotcha**: Setting a track's mode to `"disabled"` prevents the browser from downloading or parsing the track's cues. If you want to read cues programmatically without showing them on screen, set the mode to `"hidden"` instead of `"disabled"`.
3. **CORS Requirements**: If you are loading `.vtt` subtitle files from a different domain, make sure the server serves them with appropriate CORS headers, and add the `crossorigin` attribute to your `` tag. 
YouTip