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.

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