Video Callouts — animated brand chips + roadmap plan for talking-head video
The job: take a finished talking-head edit and lay animated callout chips in your brand style (and optionally a
build-on roadmap "plan" panel) over it — graphics only, audio/cut untouched. Output a new … v2 (callouts).mp4.
It renders the chips as a transparent Remotion overlay track, then ffmpeg-composites it onto the source.
The three non-negotiable rules (each learned the hard way)
-
Time against the EDITED file, not the source SRT. A re-assembled edit (segments cut out of recording order) has a totally different internal clock. Transcribe the rendered mp4's audio for real word timing:
ffmpeg -y -i "EDIT v1.mp4" -vn -ac 1 -ar 16000 audio.wav -loglevel error # faster-whisper base.en, word_timestamps=True, vad_filter=True → word-accurate cue times(If no whisper:
python3 -m venv venv && venv/bin/pip install faster-whisper.) -
Framing dictates placement + style — look at real frames first. Grab frames (
ffmpeg -ss <t> -i src -frames:v 1 f.jpg) across the video. In a typical talking-head setup the subject is center-framed, mid-chest up, hands + mic in the lower-center. Therefore:- Place callouts in the UPPER third (not the lower-third a label spec might assume — the subject's hands live there).
- Default to the dark
rectchip (carries its own#141822background = contrast-safe on any backdrop). - Use the accent
cmd(> …) style only over dark negative space (e.g. upper-right) — accent-colored text vanishes against a similarly colored backdrop.
-
Never re-encode more than once, never touch the audio.
overlay.shcomposites in a single libx264 pass (crf 16, preset slow) and stream-copies the source audio bit-for-bit.
Chip styles and theme tokens
Two chip styles, generalized to any text:
rect—[ TEXT ↓ ]in a solid raised#141822block, accent brackets, light text, secondary-accent caret. The default. Readable anywhere.cmd— muted>prompt + accent lowercase text (+ optional accent-2 caret). Transparent.
The workspace ships a neutral default theme. The tokens live in remotion/src/types.ts (PALETTE, consumed by
chips.tsx) — edit the defaults there to apply your own brand. Shipped defaults: bg #0B0D12 · card #141822 ·
border #242B3A · text #EDEFF5 · muted #8B93A7 · primary accent #5B9DFF · secondary accent #7CF2C8.
Fonts: Inter + JetBrains Mono (bundled in remotion/public/fonts/; shipped defaults, replaceable).
Motion (anti-hype)
Every chip/step enters with fade + 8px rise + a subtle 1.0→1.04→1.0 settle, ease-out, over ~0.4s;
fades out over ~0.3s. Arrow wipes are linear. No bounce, no overshoot past 1.04, no shadows/glow.
Implemented in remotion/src/motion.ts.
The roadmap "plan" panel
A build-on vertical roadmap (PlanPanel.tsx) that reveals numbered steps one at a time as the VO names
them — a calm list, not a graph. Anchor it upper-right over dark
negative space so it never covers the face. Use it on the intro's roadmap beat ("first… then… finally…").
Pipeline — two render paths
Default (animated brand chips + plan): Remotion overlay.
cd remotion
npm install --prefer-offline # Remotion 4.0 / React 19
./render.sh <cues.json> callouts-alpha.mov <durationSec> [fps] [w] [h] # → transparent ProRes 4444
../scripts/overlay.sh "src.mp4" callouts-alpha.mov "src v2 (callouts).mp4"
Cue schema: remotion/src/types.ts; a filled example: templates/cues.example.json.
Editor handoff: DaVinci Resolve FCPXML (baked, per-callout, retimable). When the editor wants the callouts on their own timeline to slide/trim/delete individually:
./scripts/davinci-export.sh <cues.json> <out-dir> <seqDurationSec> [fps w h]
This splits the cues into one clip per callout, renders each as a baked transparent ProRes 4444 .mov
(animation included), and writes intro-callouts.fcpxml placing each clip at its exact timecode on alternating
lanes (so overlapping callouts don't collide), over an empty base track. In Resolve: File → Import →
Timeline…, then drop the talking-head edit on V1 underneath — the callouts composite over the alpha, no keying.
scripts/split_cues.js + scripts/gen_fcpxml.js are the two steps if you need to run them by hand.
Give the editor a README. This is the animated multi-clip
variant of a single-PNG FCPXML handoff.
Fallback (plain burned captions, no chip/animation): ffmpeg + libass.
Burn an SRT with a force_style override (see the video-clips skill for the recipe). Good for a spoken-line
transcript caption; it cannot do the settle-scale, chip container, or
independent arrow wipe — reach for Remotion when the look matters.
cues.json schema (quick ref)
{
"fps": 30,
"cues": [
{ "text": "get started in a few hours", "style": "rect", "anchor": "upper-center",
"caret": "", "inSec": 41.0, "outSec": 47.0 },
{ "text": "not an engineer", "style": "cmd", "anchor": "upper-right", "inSec": 8.4, "outSec": 12.6 }
],
"plans": [
{ "kind": "plan", "title": "What we'll build", "anchor": "upper-right",
"inSec": 47.6, "outSec": 74.0,
"steps": [ { "label": "See the ecosystem", "revealSec": 48.2 }, … ] }
]
}
anchor: upper-center | upper-right | upper-left. style: rect | cmd. caret: "" disables the rect
caret; "↑"/"↓"/"→" for cmd. Keep text short (≤ ~4 words) — copy-paste friendly, no numeric prefixes.
Copy rules
Short, matches the spoken words, no numeric prefixes, ≤ ~4 words. Anti-hype: state the fact, don't sell it. "faster · better quality", "get started in a few hours", "pro tip: sync across agents" — not "🚀 MIND-BLOWING".
Full-frame b-roll card rules (apply to every Remotion slide/diagram comp)
Learned the hard way — these bites repeat if not written down:
- Look at the poster PNG before shipping. Every comp renders a poster at ~70% through. Open it. Every issue below was visible in the poster.
- Connectors draw edge-to-edge, never center-to-center. Compute each endpoint as the rect-edge
intersection along the line's unit direction (
min(hw/|ux|, hh/|uy|)from center). A line drawn to a card's center shows through translucent "hot" fills and stabs into opaque cards. - Arrowheads: symmetric, vector-derived, in empty space. Build the head from the line's final unit
vector (
base = tip − u·len,corners = base ± perp·halfWidth— ~36px long, ~14px half-width at 1080p). Never hand-writel -34 -6 l 12 32offsets (they skew). Land the tip in empty space — never inside a bar, card, or chip. - Number commas get balanced air. In odometer/big-number comps, give the comma glyph its own column: ~0.26em wide + ~0.09em margin each side, glyph centered. Tight commas read cramped next to full-width mono digits at 100px+ sizes.