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"`.

Selecting text track state

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

Selecting one text track

Use a track kind and, when needed, a label to select one track with normalized cues and src details.

import { useTextTrack } from '@videojs/react';

function useChapters() {
  const chapters = useTextTrack('chapters');

  return chapters?.cues.map((cue) => ({
    startTime: cue.startTime,
    endTime: cue.endTime,
    title: cue.text,
  })) ?? [];
}

import { createPlayer, createTextTrackSelector, MediaElement } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController, context } = createPlayer({ features: videoFeatures });
const selectChapters = createTextTrackSelector('chapters');

class Chapters extends MediaElement {
  readonly #chapters = new PlayerController(this, context, selectChapters);

  get cues() {
    return this.#chapters.value?.cues ?? [];
  }
}