gooseworks-ai/goose-skills / skills/video/render-vo-anchored-motion-listicle
render-vo-anchored-motion-listicle
VerifiedAssemble a narrated motion-graphic listicle video ad from a config: a voiceover (cloned or cast, in the chosen tone) reads a numbered list while N animated web-graphic beats in one branded design system (alternating tiles, big numerals, callouts) are rendered frame by frame and timed to the voiceover's words. Optional B-roll windows (a brand clip, an AI clip or a motion graphic) give the eye a break, and captions appear only inside those windows, with the voiceover mixed over a low music bed. Free, deterministic assembly; the voiceover, music and any AI clips come from create-vo-elevenlabs, create-music-elevenlabs and create-video-fal. Use for the vo-anchored-motion-listicle format.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| scripts/PIPELINE.md | markdown | 7.0 KB |
| scripts/README.md | markdown | 3.8 KB |
| scripts/config.example.json | config | 9.7 KB |
| skill.meta.json | config | 189 B |
| tests/smoke-test.md | markdown | 1.6 KB |
scripts/PIPELINE.md
View on GitHub# Pipeline — VO-anchored motion-graphic listicle
How `config.example.json` maps to the real production steps. This molecule ships a
**config + this map**, not a bundled runner: the worked example (Truehour "doctor-educator"
listicle — an example, not the default) was produced by per-project drivers in the first build (not shipped:
`voice/render_listicle_v2.py`,
`working/render_hf.py`, `working/grade_brolls_v4.py`, `working/build_master_v4.py`).
**Creative calls come from the recipe's `choices`** (asked of the user first; the demo's values are
examples only): `narrator` → `voice.mode`/`voice.voice_id`; `tone` → the script + the read;
`list_angle` → the script + `beats[]`; `visual_style` → `design.name`/`callout_style`/`accents`/
`background_tiles` (colours + fonts still from the brand kit); `music` → `music.prompt` (`none` = no bed). Drive the whole run via
`video-orchestrator-with-control-plane`.
The steps run **in order** because each depends on the last: the VO sets the timeline (its
word-level timestamps), the word times anchor every beat reveal, the beats + B-roll seed the
render, the render + concat build the silent master, and assembly mixes the VO under the music
bed + burns the window-masked captions.
## Field → source-script map
| Config field | Phase | Source step / script (in the run) | Paid? |
|---|---|---|---|
| `voice.mode`, `voice.voice_id`, `voice.model`, `voice.atempo`, `voice.script_ref` | 1 VO | ElevenLabs clone/cast (`eleven_v3`) + ffmpeg `atempo` -> `voice/vo-render.mp3` | **PAID** |
| `voice.outputs.word_timings` | 2 Transcribe | Groq `whisper-large-v3` word-level on the rendered VO -> `working/whisper/words-flat.json` | **PAID** |
| `design.*`, `beats[].hero_numeral/headline/body/callout/accent` | 3 Beats | author N hyperframes (HTML + Web Animations `window.renderAt(t)`) in ONE design system -> `working/hyperframes-v4/beat-NN.html` + `_shared.css` + `_shared.js` | free |
| `beats[].anchor_word`, `beats[].anchor_t` | 3 Beats | reveals anchored to word times in `words-flat.json` | free |
| `render_engine`, `fps` | 5 Render | `working/render_hf.py` (Playwright frame-by-frame `renderAt(t)` -> ffmpeg encode; ALL beats share fps 25) | free |
| `broll[].source`, `broll[].brand_clip`, `broll[].ai_prompt`, `broll[].t_start/t_end`, `broll[].graded` | 4 Breathers | brand clip, AI clip via `create-video-fal`, or a motion-graphic breather; trim + `working/grade_brolls_v4.py` (color-grade to palette). NO free stock source (`build_pexels_beats.py` / media-proxy stock was never wired) | brand clip / motion-graphic free; AI clip **PAID** |
| `captions`, `captions.mask`, `captions.chunk_words`, `captions.gap_close_s`, `captions.ass_format_has_name_field` | 5 Captions | Whisper words -> ASS, kept only inside B-roll windows, 2-word chunks, close on >0.4s gaps (`Name`-field header) | free |
| `music`, `music.prompt`, `music.bed_volume`, `audio_mix` | 5 Assembly | ElevenLabs Music bed (~0.18 vol, style from `choices.music`) mixed under the VO | **PAID** (music bed) |
| assembly | 5 Assembly | `working/build_master_v4.py` (concat beats + B-roll, mix VO+music, composite silent video + audio + burn window-masked captions -> `finals/master.mp4`) | free |
| `headshot` | — | kept for a FUTURE lipsync variant; UNUSED in the shipped master | — |
## 1. VO -> ElevenLabs clone/cast (config: `voice`) [PAID]
**Lock the VO FIRST — it sets the timeline.** `voice/render_listicle_v2.py` narrates the listicle
script with ElevenLabs `eleven_v3` — per `choices.narrator`, either a **cloned** voice (train from a
short reference sample of that real person, then narrate) or a **cast** `voice_id` that fits the
narrator + `choices.tone` — then `atempo` to the target pace (v3's speed
param is weak; use ffmpeg `atempo` for real time-stretch) -> `voice/vo-render.mp3`. The delivered VO
and its word-level timings, NOT the plan, set the timeline.
## 2. Transcribe -> Whisper word timings (config: `voice.outputs.word_timings`) [PAID]
Groq `whisper-large-v3` word-level on the RENDERED VO -> `working/whisper/words-flat.json` (a flat
list of `{word, start, end}`). Every beat reveal in step 3 anchors to a word time here. Whisper is
the right tool for SPOKEN VO word-level; script-window timing is only for SUNG audio (not this format).
## 3. Beats -> hyperframe authoring (config: `design`, `beats[]`)
One HTML hyperframe per beat in ONE design system: `working/hyperframes-v4/beat-NN.html`, each
exposing `window.renderAt(t)` driven by the Web Animations API so a renderer can seek any frame.
Shared `working/hyperframes-v4/_shared.css` holds the design tokens (palette, type, alternating
`background_tiles`, decorative `accents`, the callout style — look from `choices.visual_style`; the
demo used glass pills) and `_shared.js` holds
`initRenderer` + `revealWords` + easing. Reveals fire at each beat's `anchor_word`/`anchor_t` from
`words-flat.json`. Alternate the background tile per beat for rhythm; keep numerals / body type /
accents / callouts CONSISTENT so N beats read as one designed reel. This is deterministic web motion
graphics — NOT i2v.
## 4. Breather windows -> source + trim + color-grade (config: `broll[]`)
How many windows and where they land are taste calls (0..N, on support-sentence pauses). There is
**no free stock-footage source** — the old `build_pexels_beats.py` / media-proxy stock path was never
wired. Per window pick `source`: `brand-clip` (a real clip the brand supplied — best, free),
`ai-video` (`create-video-fal`, **PAID — gate it**; SCREEN-FREE people footage from the brand's own
world, matched to the spoken line), or `motion-graphic` (a free on-brand animated breather). Trim it,
then `working/grade_brolls_v4.py` color-grades it to the palette. Render B-roll
at fps 25 to match the beats. These are the ONLY windows where captions burn — on the motion-graphic
beats the on-screen type IS the caption.
## 5. Render + captions + assembly (config: `render_engine`, `captions`, `music`, `audio_mix`)
- **Render (`render_hf.py`):** for each beat, Playwright loads the hyperframe, calls
`window.renderAt(t)` per frame, screenshots it, and ffmpeg encodes -> a silent mp4 per beat. **ALL
beats MUST share fps 25** — a mismatched-fps beat stutters at the concat seam.
- **Captions:** built from `words-flat.json`, kept **ONLY inside the B-roll windows**, 2-word chunks,
closing a cue on any >0.4s word gap. The ASS `Format:` header MUST include a `Name` field — without
it the leading-comma bug eats the first field and captions silently drop.
- **Assembly (`build_master_v4.py`):** concat all beats + B-roll windows (ffmpeg demuxer) ->
`master-silent.mp4`, mix the VO (full) under a LOW ElevenLabs Music bed (~0.18 vol), composite the
silent video + the mixed audio + burn the window-masked captions, loudnorm to -14 LUFS ->
`finals/master.mp4` (1080×1920, 25fps, h264 crf18 + aac 192k, ~66s).
Re-cuts (new caption chunking, re-timed beats, swapped B-roll, a different music bed level) reuse the
existing VO / beats / B-roll and spend nothing — only the VO clone/narration, the Whisper pass, the
music bed, and any AI breather clips spend.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |