Captions layers

Captions render timed subtitle entries. Feed them an SRT string, a VTT string, or an array of { caption, startTime, endTime } objects.

// LiveFlowDemo
const $ = new iLoveVideoEditor({ width: 512, height: 512, fps: 30, backgroundColor: '#000' });

const captions = $.addCaptions(
  {
    fontSize: 9,
    fontWeight: 800,
    color: '#ffffff',
    position: [0.5, 0.5],
    textAlign: 'center',
  },
  {
    captions: [
      { caption: 'iLoveVideoEditor',           startTime: 0.0, endTime: 1.2 },
      { caption: 'renders',             startTime: 1.3, endTime: 2.2 },
      { caption: 'beautiful captions.', startTime: 2.3, endTime: 3.5 },
    ],
    maxCharsPerLine: 24,
    maxLines: 2,
  },
);
$.wait('3.5s');
captions.remove();
return $;

Input shape

// Pass typography in properties; timed entries in settings.captions
$.addCaptions(
  {
    fontSize: 2,
    fontWeight: 600,
    color: '#ffffff',
    position: [0.5, 0.85],
    textAlign: 'center',
  },
  {
    captions: [
      { caption: 'Hello world.',     startTime: 0,   endTime: 1.5 },
      { caption: 'Built from JSON.', startTime: 1.5, endTime: 3.0 },
    ],
    maxCharsPerLine: 40,
    maxLines: 2,
  },
);

Properties

Prop	Default	Notes
captions (setting)	—	Array of { caption, startTime, endTime }.
fontSize / fontWeight / fontFamily / color		Same as text layer.
backgroundColor / padding / borderRadius		Per-line pill.
position	[0.5, 0.85]	Bottom-centre by default.
maxCharsPerLine (setting)	40	Line-break hint.
maxLines (setting)	2	—

Native word motion (contract v2)

Set captionContractVersion: 2 to enable exact-copy tokens, cue-native motion, word highlighting and semantic emphasis. Token text must concatenate exactly to caption, including spaces and punctuation. Timed tokens use the same absolute source-time context as their cue.

{
  "captionContractVersion": 2,
  "captionMotionMode": "full",
  "captions": [{
    "id": "cue-1",
    "caption": "Build it faster.",
    "startTime": 0,
    "endTime": 1.5,
    "tokens": [
      { "id": "w1", "text": "Build", "startTime": 0, "endTime": 0.5, "role": "emphasis" },
      { "text": " " },
      { "id": "w2", "text": "it", "startTime": 0.5, "endTime": 0.9 },
      { "text": " " },
      { "id": "w3", "text": "faster.", "startTime": 0.9, "endTime": 1.5 }
    ]
  }],
  "captionStyle": {
    "inactiveToken": { "opacity": 0.55 },
    "activeToken": { "color": "#ffd447" },
    "emphasisToken": { "fontWeight": 900, "scale": 1.08 }
  },
  "captionMotion": {
    "cue": {
      "enter": { "preset": "captionFade", "duration": 0.12 },
      "exit": { "preset": "captionFade", "duration": 0.08 },
      "handoff": { "preset": "captionFade", "duration": 0.08 }
    },
    "token": {
      "active": { "preset": "captionTokenPop", "duration": 0.12 }
    },
    "reducedMotion": "simplify"
  }
}

Use captionMotionMode: "reduced" for the serialized accessibility fallback in both preview and export. This deliberately avoids depending on the render machine's operating-system preference, so renders stay reproducible.