Text tracks

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

Manages subtitles, captions, chapters, and thumbnail tracks.

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`	`null \| string`
Description The `<track>` element's `src` for resolving relative cue text URLs.
`textTrackList`	`MediaTextTrack<TextTrackKind>[]`
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. 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.

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, MediaElement, selectTextTrack } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

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

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