/render-absurdist-explainer

name: render-absurdist-explainer
description: Assemble an absurdist animated-explainer video ad (~38s, 9:16) from per-scene i2v clips + their measured VO windows — retime each clip to its VO, re-encode every segment to identical 30fps/libx264/yuv420p so the concat demuxer never drops frames, concat, build a REAL-product PIL end card (never AI) held static, mix VO (loudnorm I=-14) under music (loudnorm I=-26, volume 0.62, amix normalize=0), and burn libass captions last. FREE deterministic assembly (bash-free, Python + ffmpeg + PIL); the recipe supplies the clips, VO, music, product photo, palette, and caption table and gates the paid keyframe/clip/VO/music calls to their own capabilities. Use for the absurdist-explainer format.
status: active

render-absurdist-explainer

The free, deterministic renderer for the **absurdist-explainer** video ad format — an animated spot that explains one problem and how the product fixes it. The format is the mechanics: show the problem in a funny, exaggerated cartoon way, teach the product's ownable mechanism visually, show what the problem costs, bring the product in, land the fix as the climax, pay it off, end on a real-product card. One narrator voice carries the whole spot. *How* the story is told (problem → fix, how it works, a day in the life, the product as hero, or a villain arc) is the user's choice, made upstream. This capability is the **FREE assembly stage only**. All generative work (nano-banana keyframes, Seedance i2v clips, ElevenLabs VO + music) happens upstream in the recipe and is handed to this capability as files.

It ports the compose recipe validated on two earlier reference runs (both happened to use the villain arc). The recipe is deterministic — iterate the cut for free, re-roll only the offending paid beat.

Choices

The creative calls are made upstream by the recipe's `choices` and arrive here only as files and config values. This renderer is story- and style-agnostic: it never assumes a story shape, a cast, a look, a narrator or a music style.

• **`story_shape`** — how the story is told: problem → fix (no villain) / how it works /

a day in the life / the product as hero / villain arc (the problem as a cartoon villain who schemes and loses). Reaches this capability as the per-scene `caption` text and the VO files. Asked of the user; the demo used the villain arc.

• **`cast`** — who the cartoon characters are (the customer, the product as a character,

a mascot; a personified problem only on the villain arc). Reaches this capability only inside the clips. Asked of the user.

• **`narrator`** — who speaks the single VO track. Arrives as the `scenes[].vo` files.

Asked of the user; the demo used the villain (villain arc only).

• **`visual_style`** — the art style of the i2v clips (`scenes[].clip`). Asked of the

user; the demo used Pixar-style 3D. Nothing here depends on it.

• **`narrator_voice`** — the voice cast for the VO. Asked of the user; the demo used a

characterful male villain voice.

• **`music`** — the bed at `music_bed`. Asked of the user; the demo used whimsical

pizzicato + woodwinds + xylophone. The mix constants below apply to any style.

What it does (the deterministic recipe)

1. **Per-scene retime.** Each i2v clip is retimed to its **measured** VO window (`scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,fps=30,setsar=1`, then `tpad=stop_mode=clone` if the VO is longer than the clip, else a trim). Each window is snapped to a whole number of frames first. `compose.py` and `make_captions.py` use the same rule, so video cuts, VO windows and caption cues share the same cut times and a caption never outlives its cut. 2. **Identical re-encode.** Every segment is re-encoded `libx264 -crf 18 -pix_fmt yuv420p -r 30` even if already correct — a framerate mismatch makes the concat demuxer silently drop frames. 3. **Concat** all scene segments + the end card via the concat demuxer (`-c copy`). 4. **Real-product end card.** `build_endcard.py` composites the REAL retail product photo over the brand palette (flat, or sampled from the photo's own edge pixel) with a typeset wordmark + claim rows + CTA pill in PIL `ImageDraw.text` — **never an AI cartoon bottle, never AI-rendered brand text**. `compose.py` holds it static over the dwell. Set `end_card.zoom_to` above 1.0 (for example 1.04) only if you want a slow zoom. Text that would be hard to read on its background (a dark brand colour on a dark photo) is drawn in white or near-black instead, with a warning. If `end_card.vo` is set, that spoken line plays from the start of the end-card window, and the dwell is stretched to at least the line's duration + 0.5s. 5. **Mix.** VO bus `loudnorm I=-14 TP=-1.5`, music bus `loudnorm I=-26 TP=-3` then `volume=0.62`, `amix inputs=2 duration=first normalize=0`, so the music is ducked under the VO. 6. **Master pass.** The mix is measured, gained to -14 LUFS, limited, encoded to AAC and measured again. The pass repeats until the encoded audio is at -14.5..-13.5 LUFS with a true peak <= -1.5 dBFS. `compose.py` prints the measured loudness and peak. 7. **Captions last.** `make_captions.py` emits a libass `.ass` (one cue per scene, Arial 64 white / 6px outline / MarginV=330, `start = scene_start + 0.08s`, suppressed on the end card). `compose.py` burns it as the final filter so captions sit on top.

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

• `scripts/build_endcard.py` — PIL composite of the real product photo + typeset brand

layer (wordmark / product line / claim rows / accent CTA pill). Reads the same `config.json`. Run this FIRST so `end_card.image` exists before `compose.py`.

• `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 point `config.captions_ass` at nothing to sk