---
title: "Caption"
canonical_url: https://docs.zvid.io/docs/structure/properties/caption/
source: docs/structure/properties/caption.md
content_revision: 6338386a1dd87e4a
---

# Caption

`Caption` defines one subtitle segment on the video timeline.

Location: `payload.subtitle.captions[n]`. Timings are absolute project
seconds, even when visuals use scene-local timelines. Keep `start < end`;
avoid overlapping caption intervals unless simultaneous captions are intended.
The examples below are caption fragments, not complete project payloads.

```typescript
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)

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

## Example — exact word timings

```json
{
  "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](https://docs.zvid.io/docs/structure/subtitle/)
- [Word](https://docs.zvid.io/docs/structure/properties/word/)