/render-3d-character-explainer

name: render-3d-character-explainer
description: "Assemble an animated character-explainer video ad (~77s, 9:16, any art style: Pixar-style 3D, claymation, anime, paper-cut, felt) on an \"N types of X\" listicle spine: one recurring human protagonist plus one persona character per list item. Given per-scene clips, a scene timing table and narration, it trims, normalises, concatenates and mixes them, reusing the source ad's audio (restyle) or fresh per-scene voiceover over a music bed (original), loops a scene's keyframe when its clip failed, and burns captions last. Free, deterministic assembly (Python and ffmpeg, no paid calls); the recipe supplies the clips, keyframes, audio and captions. Use for the 3d-character-explainer format."
status: active

render-3d-character-explainer

The free, deterministic renderer for the **3d-character-explainer** video ad format — an animated character spot (art style is the user's choice; the demo was glossy Pixar-style 3D) built on an **"N types of X" listicle** spine, where a recurring human protagonist plus a locked cast of **N persona characters (one per list item)** carry a hook → "deeper story" → cast-reveal → one beat per list item → kicker → product test → relieved payoff. This capability is the **FREE assembly stage only**. All generative work (Nano-Banana cast anchors + per-scene keyframes, Kling-V3 i2v clips, ElevenLabs VO + music, or a source ad's audio reused verbatim) happens upstream in the recipe and is handed to this capability as files.

It ports the validated compose recipe from the worked example — a "six types" Pixar-style 3D listicle restyle (`_render_full.sh` — per-scene trim → normalize 1080×1920/fps30 → concat -c copy → mux the source audio, with a static-still fallback on any failed clip). The assembly is deterministic — iterate the cut for free, re-roll only the offending paid beat.

Choices

The recipe asks these of the user before any paid step; this capability assembles whatever comes back. None of them is fixed by the format.

• `visual_style` — the art style of the anchors, keyframes and Kling motion prompts (Pixar-style

3D, claymation, anime, paper-cut, felt). Asked of the user; the demo used glossy Pixar-style 3D.

• `narrator` — who tells the story and in whose POV the lines / captions are written. Asked of

the user; the demo used an off-screen storyteller.

• `narrator_voice` — the VO voice (ORIGINAL mode only). Asked of the user; the demo used one

ElevenLabs narrator.

• `tone` — cute/comedic, sincere, educational, dramatic, punchy; shapes the style prefix, the

delivery and the script. Asked of the user; the demo was cute and comedic.

• `protagonist` — the human's age, gender, look and outfit (locked via the world lock). Asked of

the user; the demo used a young protagonist in a single tee.

• `music` — the bed under the VO, or none (ORIGINAL mode → `music_bed`). Asked of the user; the

demo used a light instrumental underscore.

Two modes

• **Restyle mode** (`audio_mode: "restyle"`, the reference run) — re-tell a finished source

ad, beat for beat, as an animated character story in the chosen style and tone. The source ad's **audio mix (VO + music bed) is reused VERBATIM** (`source_audio`), and the per-scene `target_sec` table is inherited from the source's scene timing. No new VO or music is rendered. The trims must sum to the source audio length.

• **Original mode** (`audio_mode: "original"`) — the ad authors its own narration. Each scene

carries a measured VO cue (`scenes[].vo`, `target_sec` = the ffprobe'd VO duration) which is concatenated into a VO track (loudnorm I=-14) and optionally mixed under a `music_bed` (loudnorm I=-26 then `volume`, `amix normalize=0`).

What it does (the deterministic recipe)

1. **Per-scene retime.** Each i2v clip is trimmed to its scene `target_sec` and normalized to identical dims/fps/SAR (`scale=W:H:force_original_aspect_ratio=decrease,pad=W:H:(ow-iw)/2:(oh-ih)/2:color=<pad>,fps=30,setsar=1`). A clip **shorter** than its window is extended with `tpad=stop_mode=clone`; a longer one is `-t` trimmed. Decrease+pad (never crop) preserves the full 9:16 keyframe framing. 2. **Static-still fallback.** For any scene whose `clip` is missing or failed to render, the scene's `keyframe` PNG is looped (`-loop 1`) for `target_sec`, so the master always assembles. Fallback scenes are printed at the end. 3. **Identical re-encode + concat.** Every segment is re-encoded `libx264 -crf 18 -pix_fmt yuv420p -r 30` even if already correct — a dims/framerate mismatch makes the concat demuxer silently drop frames — then concatenated via the concat demuxer (`-c copy`). 4. **Audio.** Restyle: `source_audio` muxed verbatim (`-map 0:v -map 1:a`), clamped to the video length. Original: per-scene VO track (optional `atempo`, `apad`, `-t` clamp) → loudnorm → optionally mixed under the music bed. 5. **Captions last.** `make_captions.py` emits a libass `.ass` (one cue per scene, `start = scene_start + 0.08s`, suppressed on any scene with no caption — e.g. a product/end-card beat carrying its own typeset copy). `compose.py` burns it as the final filter so captions sit on top. Word-level energy-pop captions (Whisper on the narration) are the recipe's upstream option — produce that `.ass` externally and point `captions_ass` at it; compose burns whatever `.ass` it's handed.

Scripts (free — Python + ffmpeg, no bash, no paid calls)

• `scripts/make_captions.py` — emits the per-scene libass `.ass` from the SAME scene table

compose reads, so caption windows stay in lockstep with the cut. Run before `compose.py` (or leave `captions_ass` unset / pointing at nothing to skip captions).

• `scripts/compose.py` — the assembler: per-scene trim + identical 1080×1920/30fps re-encode

(static-still fallback on missing clips) → concat → audio (restyle verbatim / original mix) → burn captions → master mp4.

• `scripts/config.example.json` — t