Skip to content

ReferenceText tracks

defineTextTrack

Define a text track once, with the type of its cue values, to add and read it with

Import

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

defineTextTrack returns a track definition: a track’s kind, and optionally its label and language, typed with the value its cues carry. A definition works anywhere a text track filter does, matching tracks by kind, label, and language. Reading through it types each cue’s value, and adding a track from it checks the cues you pass against that type.

Usage

Pass the value type as a type parameter. The type isn’t checked at runtime.

import { defineTextTrack, getActiveTextCues, type TextCueInit } from '@videojs/html';

interface Quiz {
  question: string;
}

const quizTrack = defineTextTrack<Quiz>({ kind: 'metadata', label: 'quiz' });

const player = document.querySelector('video-player')!;
const cues: TextCueInit<Quiz>[] = await fetch('/api/quiz').then((res) => res.json());

player.store.addTextTrack(quizTrack, { cues });

player.store.subscribe(() => {
  const [cue] = getActiveTextCues(player.store, quizTrack);
  console.log(cue?.value?.question);
});

Schemas

Pass a schema to check values where they’re read. It takes any Standard Schema, the validation interface zod, valibot, ArkType, and other libraries implement, and the value type comes from the schema’s output.

import { z } from 'zod';

const QuizSchema = z.object({ question: z.string() });

const quizTrack = defineTextTrack({ kind: 'metadata', label: 'quiz', schema: QuizSchema });

Readers skip a cue whose value fails the schema, and warn in development. Each cue is checked once per schema. Schemas must be synchronous; an asynchronous schema fails every value. Adding a track doesn’t run the schema.

Built-in definitions

chaptersTrack matches every chapters track and types the values chapter formats carry. hlsMetadataTrack matches the metadata track hls.js publishes ID3 and EXT-X-DATERANGE metadata on.

Exports

Export Description
TextTrackDefinition A track definition. Its type parameter is the cue type it reads.
TextTrackIdentity What identifies a track: kind, label, and language.
InferTextTrackCue The cue type a definition reads, as in InferTextTrackCue<typeof quizTrack>.
InferSchemaOutput The value type a schema produces.
StandardSchemaV1 The Standard Schema interface a schema implements.
StandardSchemaV1Props The properties a Standard Schema carries under its ~standard key.
StandardSchemaV1Result What a Standard Schema’s validate returns.

API Reference

With Schema

defineTextTrack<Schema extends StandardSchemaV1>(init): TextTrackDefinition<MediaTextCue<InferSchemaOutput<Schema>>>

Define a text track whose cues carry a value checked by a schema, such as one from zod or valibot. Cues whose value fails it are skipped where they're read.

const quizTrack = defineTextTrack({ kind: 'metadata', label: 'quiz', schema: QuizSchema });

Parameters

ParameterTypeDefaultDetails
init*object—

Return Value

PropertyTypeDetails
kind'subtitles' | 'captions' | 'descripti...
labelstring | undefined
languagestring | undefined
schemaobject

With Type

defineTextTrack<Value = unknown>(init): TextTrackDefinition<MediaTextCue<Value>>

Define a text track whose cues carry a value of a given type. The type is not checked at runtime; pass a schema for that.

const quizTrack = defineTextTrack<Quiz>({ kind: 'metadata', label: 'quiz' });

Parameters

ParameterTypeDefaultDetails
init*object—

Return Value

PropertyTypeDetails
kind'subtitles' | 'captions' | 'descripti...
labelstring | undefined
languagestring | undefined
schemaobject