# Text tracks

Subtitles, captions, and chapter track state for the player store

Manages subtitles, captions, chapters, and thumbnail tracks.

`textTrackList` lists the media’s tracks, then the tracks an app adds to the player with this feature’s `addTextTrack()`, described with the [text cues feature](https://videojs.org/docs/framework/html/reference/api/feature-text-cues). Each track’s `source` is `'media'` or `'app'`. An app `captions` or `subtitles` track is copied into the media so the browser can draw it, and it’s selected and listed like the media’s own; its copy isn’t listed separately. Media without text tracks of their own, such as embeds, list only app tracks.

A default `kind="chapters"` track can also divide the [time slider](https://videojs.org/docs/framework/html/reference/components/time-slider) into chapter ranges and label the chapter at the current interaction position. When the media has no chapters track, `chaptersCues` reads the first chapters track the app added instead.

This feature doesn’t track cues as they become active. The text cues feature does, for metadata and chapters tracks and for any track a reader asks for.

`thumbnailsTrack` is the first `kind="metadata"` track labeled `thumbnails`, or `null` when there is none. When the media has none, it’s the first such track the app added, with its `src` as the base for image URLs. Its `crossOrigin` reports the media component’s CORS mode, or `null` when the media is not CORS-enabled. [Thumbnail](https://videojs.org/docs/framework/html/reference/components/thumbnail) reads it to fetch sprite sheets the same way the browser fetched the track.

## Import

```ts
import { textTrackFeature } from '@videojs/html';
```

The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `textTrackList` | `MediaTextTrack[]` | Every text track: the media's, then those the app added through the player. `source` tells them apart. |
| `subtitlesShowing` | `boolean` | Whether a captions/subtitles track is showing. |
| `chaptersCues` | `MediaTextCue[]` | Cues from the media's first `kind="chapters"` track, with cue ends clamped to a finite media duration. When the media has none, cues from the first chapters track the app added, where a chapter without an end runs to the next one and the last to the end of the media. |
| `thumbnailsTrack` | `{ cues: MediaTextCue[]; src: string \| null; crossOrigin: 'anonymous' \| 'use-credentials' \| null } \| null` | The first thumbnails track, or `null` when there is none. |
| `addTextTrack` | `{ <Cue extends MediaTextCue>(track: TextTrackDefinition<Cue>, content?: TextTrackContent<InferCueValue<Cue>>): TextTrackHandle<InferCueValue<Cue>>; <Value = unknown>(init: TextTrackInit<Value>): TextTrackHandle<Value> }` | Add a text track from the app. It works on any media, sits next to the media's tracks in `textTrackList`, and its cues are read like theirs. Like a `<track>` element, it stays until it's removed, through source changes and media swaps. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `toggleSubtitles` | `(forceShow?: boolean) => boolean` | Toggle captions/subtitles visibility. Showing enables one caption/subtitle track. A track already showing stays selected. Otherwise, selection prefers the last track shown, then a track matching the browser language, then the first available track. Returns whether a track is showing. |
| `selectSubtitlesTrack` | `(id: string \| null) => void` | Show the captions/subtitles track with `id`, or turn captions/subtitles off with `null`. |
| `removeTextTrack` | `(id: string) => void` | Remove a track the app added. Tracks from the media stay. |

### Selector

Pass `selectTextTrack` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to text track state. Returns `undefined` if the text tracks feature is not configured.

**captions-button.ts**

```ts
import { createPlayer, UIElement, selectTextTrack } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class CaptionsButton extends UIElement {
  readonly #textTracks = new PlayerController(this, selectTextTrack);
}
```

---

HTML documentation: https://videojs.org/docs/framework/html/llms.txt
All documentation: https://videojs.org/llms.txt
