Caption Titles

Animate the letters and their content

For a number that changes during a text clip, store textAnimator on an animation with kind: "ticker", from, and to. It also accepts decimals, padTo, prefix, and suffix. Set groupSeparator to "," to show thousands as 2,847; omitting it keeps existing tickers ungrouped. For a deterministic decode into the clip's authored text, use kind: "scramble" with a fixed seed and optional charset. These operate over the animation window, so a held final frame shows the finished value.

{"id": "count-in", "role": "in", "preset": "fade", "durationMs": 900,
 "textAnimator": {"kind": "ticker", "from": 1, "to": 7,
  "padTo": 2, "suffix": " / 07"}}

For unit-by-unit motion, set stagger.unit to character, word, or line and give it offsetMs. With a text stagger, styleTracks can target glyph.color, glyph.blurPx, or glyph.trackingPx. The colour uses CSS colour values; blur and tracking use sequence pixels. Use text.color or text.fill.stops.0.color for a whole line. A text fill gradient also exposes text.fill.angle and stop offsets. The target must refer to an existing style field; text.color is hidden while a gradient fill is set.

To lay a title along a curve, set textStyle.path to an SVG path in normalized canvas coordinates. This places the baseline on the path. It does not make each character travel along it. Shape and mask paths can morph through shape.d and mask.d style tracks when both paths have matching commands and point counts. Use followPath when the whole clip should move along a path.

edit_timeline's animate_clip input accepts presets and custom numeric curves, but does not accept textAnimator or styleTracks; those fields are dropped from that call. To author them, read the current document and use set_timeline_document with the animation fields in the clip. That call validates the complete document and snapshots the previous state. Preserve the other tracks and clips from the document. motion-graphics owns the full tool contract.

Build and verify

Add separate overlay and subtitle tracks. For each map item, add scrim before text, apply the locked tier style, then animate it with that tier’s entry and exit preset. No hard cut-on. Use stagger only for tone-appropriate kinetic captions. Keep all text within safe margins and clear of faces and product moments.

Two facts about stacking decide whether the text is seen at all. The lowest track index draws on top, so the scrim's track index sits between the picture's and the text's — picture, scrim, text, in descending index. And word-level captions generated from a voiceover clip composite above every real track regardless of where that clip sits, so no title can cover them: time a T1 around the narration rather than over it.

Verify in two passes, and they answer different questions. validate_timeline reads the document: text_illegible (size, or under 3:1 contrast against the text's own background plate or a full-frame shape behind it), font_not_portable, stagger_compressed, animation_exceeds_clip, overlaps, and clips shorter than a frame. Its contrast check refuses to guess — a translucent scrim, gradient type or a plate it cannot prove is behind the text produces no finding — so a silent pass is not a pass. Then preview_timeline_frame at each item's entry midpoint, a held moment, and its exit: that is where text over a busy plate, a scrim covering a face, or a caption still finishing when its clip ends shows up. Re-read the map against the frames: timing, reading floors, scrim ordering, one CTA at the end. Stop after authoring the text layer unless rendering is requested.