Captions

A React block (a whole screen) in Beamline's CMS & media app.

Captions for a video, by speaker and by style. Caption layers are bound to a speaker (or all speakers), each with its own style and place, top or bottom; the preview shows every layer's words at the playhead in its style, and the playhead is a grip on the scene's timeline where each speaker's words sit in that speaker's colour, the same colour that marks the speaker's layer and caption. A layer bound to a speaker who isn't in the script is said as unresolved; overlapping layers and a layer with no words at the moment are said; removing a layer never touches the script. The style library is searched, filtered by kind and sorted, each style shown on a sample line and named in words; Restyle the selected layer and Add as a new layer are separate actions, so no duplicate is made by accident; the scope, this scene or all scenes, says how many scenes it changes before applying; an unavailable style says why.

Use it for

Styling captions or subtitles over a video, podcast or course recording, per speaker and per scene.
Any preset library that applies to a selected item or adds a new one, with a scope that must be said before it applies.

Not for

Playing a video (video) or reading a transcript along with it (transcript-viewer).
Cutting the video itself (a timeline editor).

Anatomy

header: the product's mark, Captions, the scenes as numbered toggles
stage: the frame with the scene and time, each layer's current words at its place in its style (the selected layer outlined); the timeline with one lane per speaker, their words as marks in the speaker's colour, the playhead a grip; the speakers with their colour and the scene's span
layers: the scene's caption layers (speaker colour, name, speaker, style, position) with unresolved, no words now and overlap said, a menu to remove; the selected layer's speaker and position
styles: search, sort, kind; style cards with a sample line, name and kind, or why it is unavailable; Apply to this scene or all scenes with what that changes; Add as a new layer and Restyle the selected layer

States

layers: none, one selected, speaker unresolved, no words at the moment, overlapping, removed
styles: browsing, filtered, none match, picked, unavailable, applying, applied, refused
scope: this scene, all scenes
loading: shaped skeletons
phone: the stage, then layers and styles stacked
right to left: mirrored; captions keep their own direction
reduced motion: through the tokens

Keyboard

On the playhead: Left/Right a quarter second, Shift two seconds, Home/End the scene's ends
Tab through the scenes, the layers (Enter selects), their menu and properties, the style search, kinds, cards (Enter picks), the scope and the actions

Motion

The playhead follows the hand; captions change with the words. Nothing runs at rest.

Props

Prop	Type	Default	Description
`speakers` (required)	`Speaker[]`	—
`words` (required)	`TimedWord[]`	—
`scenes` (required)	`Scene[]`	—
`presets` (required)	`CaptionPreset[]`	—
`layers` (required)	`CaptionLayer[]`	—
`defaultScene`	`string`	—	The scene being edited.
`defaultLayer`	`string \| null`	—
`defaultTime`	`number`	—	The playhead, in seconds.
`onApply`	`((r: ApplyRequest) => Promise<{ layerId: string; }>)`	—	Restyle a layer or add one. Reject with an Error: nothing changed, the reason said.
`onLayerChange`	`((layer: CaptionLayer) => Promise<unknown>)`	—
`onRemoveLayer`	`((layerId: string) => Promise<unknown>)`	—	Remove a caption layer; the transcript is never touched.
`loading`	`boolean`	—
`product`	`string`	—
`className`	`string`	—	Classes on the documented visual root; no override by default.
`ref`	`Ref<HTMLDivElement>`	—	Receives the documented native target or imperative handle; omitted by default.

Built from

Dependencies

lucide-react

Import

import { Captions } from "@beamline/captions";

Get it

Captions is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. Get Beamline · Connect your agent