/render-cosmic-mythology-voiceover

name: render-cosmic-mythology-voiceover
description: Assemble a cosmic-mythology-voiceover reel from a config — one spoken voiceover carries the whole narrative while N curated stills in one chosen look are weighted beat-synced across the delivered VO duration (cut_dur = VO_dur times weight over the weight sum, so emotional beats hold longer), Ken-Burns-zoomed per still (scale 2x, center crop, zoompan, fade-in first and fade-out last), ffmpeg-concatenated, the VO composited under the picture (libx264 crf18 plus aac), the ONE on-screen hook line faded on over the open with a drawtext alpha window, and Whisper/VEED captions burned along the bottom — never in-world text on a still. This is the FREE deterministic assembly stage (weighted sequence plus Ken-Burns plus concat plus VO composite plus hook overlay plus caption burn); the VO and the stills come from create-vo-elevenlabs and create-image-fal. Use for the cosmic-mythology-voiceover format.
status: active

render-cosmic-mythology-voiceover

Assemble a **cosmic-mythology-voiceover** reel from a config: a faceless, cinematic storytelling video where one spoken **voiceover** carries the whole narrative over a slow, weighted **Ken-Burns zoom** across curated stills in ONE locked look, with ONE on-screen hook line and burned captions. The narrator, voice, tone, story shape, visual world and art style are the recipe's user choices — this capability only assembles what it is given (the demo: a warm contemplative "the steady star, not the brightest" reframe over deep-indigo + gold cosmic stills). This capability is the **FREE, deterministic assembly** — the weighted beat-sync sequencing, the Ken-Burns render, the concat, the VO composite, the hook overlay, and the caption burn.

`scripts/config.example.json` is the worked example — reference only, never the default (Peerlark Optics "The North Star isn't the brightest", ~31s 1080×1920 9:16, 12 weighted Ken-Burns cuts); `scripts/PIPELINE.md` maps every config block to its production step and `scripts/README.md` documents the free assembly.

Run

There is a single runnable script — `scripts/render.py` (config-driven, ffmpeg + Pillow only, NO API keys and NO `drawtext`/`libass` required):

python3 scripts/render.py --config config.json --vo working/vo2/vo_atempo.mp3 \
  --stills-dir working/stills --out working/final.mp4 \
  [--words working/vo2/words.json] [--endcard working/endcard.png]

This is the **FREE, deterministic** assembly stage — it spends nothing. The paid inputs are separate capabilities — the spoken VO (`create-vo-elevenlabs`, ElevenLabs `eleven_v3` from a tone-tagged script, atempo time-stretched so the delivered duration sets the timeline) and the 4–6 hero stills in one look pack (`create-image-fal`, Flux Pro 1.1, reused as repeats to reach the ~10–12 cuts). Given the VO + the stills + the per-cut weight array + the hook line, `render.py` distributes the cuts across the VO duration by the weighted formula, Ken-Burns-renders each still, concats, composites the VO, fades the hook line on over the open, burns the captions, and (if `--endcard` is passed) appends a brand end card → the master + a poster. Re-cuts reuse the existing VO / stills and spend nothing. See `scripts/README.md` §0 for the full arg contract.

Contract (the free assembly)

• **The spoken VO carries the narrative — no talking head, no sung song.** The generated/supplied

VO IS the audio bed (no music bed by default); do not add a presenter or a second bed.

• **Plan the timeline AROUND the delivered VO duration.** The VO is atempo time-stretched (clamp

the factor ≤ ~1.25 so the voice never chipmunks); its delivered length sets the timeline — never trim the VO to a pre-planned grid.

• **Weighted beat-sync, not a fixed grid.** For each cut, `cut_dur = VO_dur × weight / Σweights` —

heavier weights hold longer on the emotional beats (the open, the turn, the close); the setup cuts run shorter. Every cut stays proportional to the whole VO.

• **Ken-Burns per still.** Render each still with scale 2×, center crop, and a `zoompan` to the

configured `zoom_end` (~1.10); apply `zoom_out` on the flagged cuts; `fade_in` on the FIRST cut and `fade_out` on the LAST. Stills are reusable — the sequence repeats a few across the cuts.

• **ONE look, no in-world text.** Every still reads in the single chosen look (the demo's:

deep-indigo + gold + volumetric light); the reel's only text is the hook + the captions, added in post (the "no text, no words" descriptor keeps words off the stills).

• **ONE hook line, alpha-faded on over the open.** Burn the single hook line over the OPEN only

(fade in ~0.5s, hold, fade out ~0.6s) — never a persistent caption, never in-world. `render.py` does this with a PIL PNG + ffmpeg `fade=…:alpha=1` (no `drawtext` dependency, since stock ffmpeg often lacks it); an ffmpeg `drawtext` alpha window is an equivalent alternative where available.

• **Captions from Whisper — bottom, white.** VEED/Whisper subtitle burn tracks the spoken VO in the

bottom third, white `#FFFFFF`. If the host ffmpeg lacks libass (no `subtitles`/`ass` filter), render the cues as timed PIL PNG overlays (ffmpeg `overlay=…:enable='between(t,st,en)'`) at the same bottom placement — a free local Whisper + ffmpeg burn is the fallback to the VEED tier.

• **FFmpeg composite, deterministic, FREE.** ffmpeg-concat the Ken-Burns clips, composite the VO

under the picture (libx264 `crf 18` + aac 192k), burn the hook alpha-fade + the caption track → a 1080×1920 h264+aac master (~31s). No paid calls, no keys (the local caption fallback is free).