Text tracks

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

Manages subtitles, captions, chapters, and thumbnail tracks.

A default kind="chapters" track can also divide the time slider into chapter ranges and label the chapter at the current interaction position.

When a thumbnail track is present, thumbnailTrackCrossOrigin reports the media element’s CORS mode, or null when the media is not CORS-enabled. Thumbnail reads it to fetch sprite sheets the same way the browser fetched the track.

Import

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

The liveVideoFeatures and videoFeatures feature bundles include this feature.

API Reference

State

Property	Type	Details
`chaptersCues`	`MediaTextCue[]`
Description Cues from the first `kind="chapters"` track.
`thumbnailCues`	`MediaTextCue[]`
Description Cues from the first `kind="metadata" label="thumbnails"` track.
`thumbnailTrackSrc`	`string \| null`
Description The `<track>` element's `src` for resolving relative cue text URLs.
`thumbnailTrackCrossOrigin`	`'anonymous' \| 'use-credentials' \| null`
Description The media element's CORS mode, mapped through the CORS-settings-attribute rules, or `null` when it is not in CORS mode. Thumbnail UI fetches the sprite sheets the cues point at with this mode, since a cross-origin `<track>` only loads at all when the media element is CORS-enabled.
`textTrackList`	`MediaTextTrack[]`
Description All text tracks available on the media element.
`subtitlesShowing`	`boolean`
Description Whether captions/subtitles are currently enabled.

Actions

Action	Type	Details
`toggleSubtitles`	`(forceShow: boolean) => boolean`
Description Toggle captions/subtitles visibility. Showing restores the track that was last showing, or the first caption/subtitle track when there is none. Returns the new enabled value.
`selectSubtitlesTrack`	`(value: string) => void`
Description Select a captions/subtitles track by menu value, or disable with `"off"`.

Selector

Pass selectTextTrack to PlayerController to subscribe to text track state. Returns undefined if the text tracks feature is not configured. Use TextTrackController to create or observe one track and its cues.

import { selectTextTrack, usePlayer } from '@videojs/react';

function CaptionsButton() {
  const tracks = usePlayer(selectTextTrack);
  if (!tracks) return null;

  return (
    <button onClick={() => tracks.toggleSubtitles()}>
      {tracks.subtitlesShowing ? 'Hide captions' : 'Show captions'}
    </button>
  );
}

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);
}