CaptionsController

Captions and subtitles for a media element: tracks from cues, WebVTT text or a URL, one shown at a time, kept above your controls.

Reach for it when you build your own video player and the captions button, the language menu and the placement above the controls are yours. It works on any HTMLMediaElement and owns only the tracks it adds.

Import

import {
	CaptionsController,
	createCaptionsController,
	type CaptionTrackSource,
	type CaptionsState,
} from '@ecopages/radiant-ui/controllers';

Try it

A six second silent clip, generated in the page, with two caption tracks. Press Play, then Captions (or c while the example has focus). The language button switches the track, also while captions are off, and the cues stay above the control bar.

Captions off

<div data-example="captions">
	<div data-stage style="position: relative; width: 320px; max-width: 100%; height: 180px; background: #111">
		<video muted style="display: block; width: 100%; height: 100%"></video>
		<div
			data-controls
			style="position: absolute; inset: auto 0 0; display: flex; gap: 0.5rem; padding: 0.5rem; background: rgb(0 0 0 / 0.6)"
		>
			<button type="button" data-action="play">Play</button>
			<button type="button" data-action="captions" aria-pressed="false">Captions</button>
			<button type="button" data-action="language" data-language="en">English</button>
		</div>
	</div>
	<p data-status>Captions off</p>
</div>
import { CaptionsController, type CaptionsState } from '@ecopages/radiant-ui/controllers';

const TRACKS = [
	{
		language: 'en',
		label: 'English',
		cues: [
			{ start: 0, end: 2.5, text: 'Captions are a track of cues' },
			{ start: 3, end: 5.5, text: 'They stay above the controls' },
		],
	},
	{
		language: 'it',
		label: 'Italiano',
		cues: [
			{ start: 0, end: 2.5, text: 'I sottotitoli sono una traccia di cue' },
			{ start: 3, end: 5.5, text: 'Restano sopra i controlli' },
		],
	},
];

export function mount(root: HTMLElement): () => void {
	const video = root.querySelector('video')!;
	const controls = root.querySelector<HTMLElement>('[data-controls]')!;
	const play = root.querySelector<HTMLButtonElement>('[data-action="play"]')!;
	const toggle = root.querySelector<HTMLButtonElement>('[data-action="captions"]')!;
	const language = root.querySelector<HTMLButtonElement>('[data-action="language"]')!;
	const status = root.querySelector('[data-status]')!;
	const url = silentUrl(6);
	video.src = url;

	const captions = new CaptionsController({
		getMedia: () => video,
		getAvoid: () => controls,
		tracks: TRACKS,
		onState: (state: CaptionsState) => {
			toggle.setAttribute('aria-pressed', String(state.enabled));
			status.textContent = state.enabled ? `Captions on: ${state.language}` : 'Captions off';
		},
	});
	captions.attach();

	const onKey = (event: KeyboardEvent) => {
		if (event.key === 'c' && !event.ctrlKey && !event.altKey && !event.metaKey) {
			captions.toggle();
		}
	};

	play.addEventListener('click', () => (video.paused ? void video.play() : video.pause()));
	toggle.addEventListener('click', () => captions.toggle());
	language.addEventListener('click', () => {
		const next = captions.getState().tracks.find((track) => track.language !== language.dataset.language)!;
		captions.setLanguage(next.id);
		language.dataset.language = next.language;
		language.textContent = next.label;
	});
	root.addEventListener('keydown', onKey);

	return () => {
		root.removeEventListener('keydown', onKey);
		captions.destroy();
		URL.revokeObjectURL(url);
	};
}

silentUrl(seconds) returns an object URL of a silent WAV built in memory; it is in the page script. mount runs once for each example element on the page, and the function it returns undoes it; see how the examples run.

Config

OptionMeaning
getMediaThe media element, read on attach() and refresh(). null while it is not rendered yet: no tracks until a refresh() finds it.
tracksThe tracks, as a fixed list. Or:
getTracksThe tracks, read on attach() and refresh(). Use one of the two, or neither with adoptExisting.
adoptExistingAlso take over the captions and subtitles tracks the element already has, <track> children included. Optional.
render'native' (default): the browser draws the cues. 'overlay': you draw them, with getOverlay.
getOverlayWith render: 'overlay': the element the active cue text is written into. Required there.
getAvoidThe element native cues stay above, such as a controls bar, or null for the bottom of the media. Optional; without it the browser places the cues.
onStateCalled with a CaptionsState when something changes, and once on attach(). Optional.
onErrorCalled with an Error and the track's CaptionTrackInfo for each track that could not be fetched or parsed. It never throws. Optional.

A CaptionTrackSource has a language (BCP 47), a label, an optional id (default ${language}-${kind}) and kind (captions, the default, or subtitles), and exactly one source of cues; the type allows no more than one:

FieldThe cues are
cuesA list of { start, end, text } in seconds, added as VTTCues to a track made with addTextTrack. No parsing, no network.
vttWebVTT text, starting with WEBVTT. It becomes a <track> element with a Blob URL and the browser parses it, so it does not depend on a server that serves .vtt files.
srcA URL the controller fetches and treats as WebVTT text, so a missing or unknown extension does not matter. The page must be allowed to fetch it (same origin or CORS). A failed fetch makes the track error.

State

getState() and onState give a CaptionsState:

FieldMeaning
enabledA track is selected and shown.
languageThe language of the shown track, or null while captions are off.
tracksEach track's id, language, label, kind and status: loading, ready or error.
activeTextThe text of the cues active now, one per line. Read from the element when you call getState().

onState is called once on attach(), as MediaController does, and then only when enabled, language, the list of tracks or a status changes. It is not called for each cue, with one exception: with render: 'overlay', activeText is part of the comparison, so it is also called when the active cue changes.

Methods

MethodDoes
enable(language?)Shows a track: the one language names (an id first, then a language tag, where pt matches pt-BR), or the one selected last, or the first. Returns false and changes nothing when there is no such track.
disable()Hides the captions.
toggle()disable() while shown, otherwise enable().
setLanguage(idOrLanguage)Selects a track. While captions are on it switches; while off it only remembers the choice for the next enable(). Returns whether a track was found.
refresh()Reads getMedia and getTracks again. Tracks that are gone are removed, new ones added, and a track whose source object changed is made again. Call it when the tracks or the avoided element change.
attach() and destroy()With a host, createCaptionsController(host, config) calls them on connect and disconnect; see bindController.

Captions start off. Exactly one track is shown at a time: the controller sets every track it owns to disabled except the selected one.

Placement

A browser draws a caption at the bottom of the video, which is where your controls are. With getAvoid, the controller sets each cue to snapToLines = false, lineAlign = 'end' and a line that is the percentage of the media height at which the avoided element starts, measured from the two bounding boxes. A ResizeObserver on the media element and on the avoided element places the cues again, so a control bar that wraps to two rows on a narrow screen pushes them up. A media element with no height (not displayed) is skipped until it has one. With render: 'overlay' nothing is placed: position the overlay element yourself.

Draw the cues yourself

const captions = new CaptionsController({
	getMedia: () => video,
	tracks,
	render: 'overlay',
	getOverlay: () => caption,
});

The controller keeps the selected track hidden, listens to cuechange, and writes the active cue text into the element as textContent (never as HTML), joined by line breaks when several cues are active, and clears it when none is. The text is the text content of the parsed cue (getCueAsHTML().textContent), so WebVTT markup such as <i>, <v Name> and timestamps is dropped and nothing is ever inserted as HTML. Formatting is not carried over; if you need italics, read the cues from the track yourself. The overlay is yours to style and place.

Accessibility

The toggle is your button. Give it one name that does not change and say whether it is on with aria-pressed, from onState:

const captions = new CaptionsController({
	getMedia: () => video,
	tracks,
	onState: (state) => {
		button.setAttribute('aria-pressed', String(state.enabled));
	},
});
button.addEventListener('click', () => captions.toggle());
button.textContent = 'Captions';

A name that changed with the state ("Turn captions on") would be read together with the pressed state. A single-letter shortcut is optional and is a pattern, not something the controller installs. If you add one, c is the usual key; ignore it with Ctrl, Alt or Meta held, and while the user types in a field:

player.addEventListener('keydown', (event) => {
	const typing = (event.target as Element).closest('input, textarea, select, [contenteditable]');
	if (event.key === 'c' && !event.ctrlKey && !event.altKey && !event.metaKey && !typing) {
		captions.toggle();
	}
});

A language menu is a list of your own buttons or a select built from state.tracks, with setLanguage(track.id).

Native cues are drawn and exposed by the browser. For an overlay, whether to use a live region is a trade-off the host decides, not a rule. Captions are usually already presented visually, in step with the audio, so a live region makes a screen reader repeat every cue over audio the user may already hear. It can be worth offering as an opt-in for a user who cannot hear the audio and reads speech on a braille display. Hiding the overlay from assistive technology (aria-hidden) is the same kind of choice: hidden, a screen reader user is not given text that duplicates the audio; visible, the current caption can be read by moving through the page.

Lifecycle

Every track the controller adds is its own, so two controllers on one element do not change each other's tracks. vtt and src tracks are <track> elements, removed on destroy() with their Blob URLs revoked. cues tracks are made with addTextTrack, which a browser cannot undo: destroy() removes their cues and sets them disabled, and the empty track stays in textTracks until a controller on that element asks for the same kind, label and language, which reuses it. That empty disabled track cannot be removed, and the reuse only bounds how many there are. Tracks the controller did not create are not touched unless adoptExisting is set; adopted tracks get their previous mode back on destroy(). Adopt on one controller per element: when two controllers with adoptExisting share an element, the first claims the tracks and the second finds them taken. A track still loading is hidden so the browser loads it, and disabled after.

destroy() stops listening and observing at once, aborts a fetch in flight (which then writes nothing), and releases the tracks in a microtask that an attach() in between cancels. Moving the element in the DOM runs cleanup, then connect, so it keeps its tracks and its selection. onState is not called after destroy().

Protected hooks

None. The decisions an owner changes are config: which tracks, how they are drawn, what they avoid.