Communitygithub.com

video-callouts

Shows an agent how to plan, build, or cut "video callouts" so the concrete output is a finished video cut. The procedure moves through The three non-negotiable rules (each learned the hard way), Chip styles and theme tokens, Motion (anti-hype). Use it when a new assignment calls for this craft.

What is video-callouts?

video-callouts is a Claude Code agent skill that shows an agent how to plan, build, or cut "video callouts" so the concrete output is a finished video cut. The procedure moves through The three non-negotiable rules (each learned the hard way), Chip styles and theme tokens, Motion (anti-hype). Use it when a new assignment calls for this craft.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jordanurbs/agentic-video-os/tree/HEAD/.claude/skills/video-callouts

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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)

  1. 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.)

  2. 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 rect chip (carries its own #141822 background = 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.
  3. Never re-encode more than once, never touch the audio. overlay.sh composites 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 #141822 block, 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:

  1. 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.
  2. 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.
  3. 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-write l -34 -6 l 12 32 offsets (they skew). Land the tip in empty space — never inside a bar, card, or chip.
  4. 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.

Related Skills