Caption

Caption defines one subtitle segment on the video timeline.

interface Caption {
  start: number;
  end: number;
  text?: string;
  words?: Word[];
}

Property	Required	Notes
start	Yes	Caption start time in seconds.
end	Yes	Caption end time in seconds.
text	Unless words given	Full caption text. Word timings are auto-generated when words is omitted.
words	Unless text given	Exact word-level timings (e.g. from a transcription model).

Each caption needs text and/or words. When only text is provided, word timings are distributed across the caption window proportionally to word length — every word-timed animation (karaoke, highlight, fill, …) works without hand-authored timings.

Example — text only (auto-timed)

{ "start": 0.5, "end": 2, "text": "Welcome to our video" }

Example — exact word timings

{
  "start": 0.5,
  "end": 2,
  "text": "Welcome to our video",
  "words": [
    { "start": 0.5, "end": 0.9, "text": "Welcome" },
    { "start": 0.9, "end": 1.1, "text": "to" },
    { "start": 1.1, "end": 1.4, "text": "our" },
    { "start": 1.4, "end": 2, "text": "video" }
  ]
}

Used By

• Subtitle
• Word