/vox-director

name: vox-director
description: >
  Turn ONE topic into a finished Vox-style paper-collage explainer / ad video, end to end
  on the Atlas Cloud API + local ffmpeg — script, collage keyframes, motion, voice-over,
  music, captions, all automated. Use this whenever the user wants a "Vox style" video,
  a paper/torn-paper collage animation, a "motion collage", a narrated explainer or short
  ad built from AI-generated collage posters, a scrapbook-style tribute, or wants to turn
  a topic / product / person into a punchy narrated collage video — even if they don't say
  the word "Vox". Also use when reproducing Stav Zilber / rom1trs / Higgsfield-style collage
  ad workflows.
  Three input modalities: a topic (B-roll), a talking-head video (A-roll mode), or a single
  photo of a person/product anchored into the collage (C-roll mode).
  Triggers: "vox video", "collage video", "motion collage", "paper collage
  explainer", "make a collage ad", "turn this topic into a collage video", "turn my
  photo/this product shot into a collage video".

Vox Director

Turn a one-line topic into a finished **Vox-style paper-collage video**: a bold, punchy, narrated explainer/ad where each beat is a torn-paper collage poster that comes alive, with voice-over, music and captions. Runs on **one Atlas Cloud API key** + local **ffmpeg**.

The look is the modern editorial paper-collage popularized by Vox explainers and creators like Stav Zilber / rom1trs: hand-cut paper cut-outs, torn edges, tape, halftone dots, newspaper clippings, bold flat color per beat, big cut-out headlines.

The core idea (read this first)

The Vox collage look and the collage motion are **two different steps**:

1. **The look is born in the IMAGE step.** Each beat is a finished collage *poster* made by a text-to-image model. All the collage DNA (torn paper, cut-outs, halftone, bold color, headline text) lives in that image. If the image isn't a rich collage, nothing downstream will save it. 2. **The motion is added after.** By default an AI video model animates the whole poster (the "living poster" path — simple, automated). For dramatic *piece-by-piece* assembly you cut the poster into parts and drive them with the local keyframe engine (advanced path).

Everything hinges on the prompts. **Before writing any image or video prompt, read `references/prompt-guide.md`** — it has the exact prompt structures that make the difference between "a real Vox collage" and "a moving PowerPoint".

Prerequisites (check, don't skip)

• `echo "${ATLASCLOUD_API_KEY:+set}"` — if empty, tell the user to set it (get one at

https://www.atlascloud.ai/console/api-keys) and stop.

• `command -v ffmpeg ffprobe` — required for assembly (`brew install ffmpeg` on macOS).
• `python3 -c "import PIL"` — Pillow, for captions/watermark overlays.

Standard workflow (topic → film)

This is the default, most-automated path. Every stage is one script, all driven by a single `beats.json` per project under `out/<project>/`.

1. **Topic → beat map.** First **read `references/beat-layer.md`** (the story layer) and pick a narrative `arc` that fits the topic (`timeline` for history, `pas`/`bab` for ads, `how_it_works` for explainers, `man_in_hole` for transformations, …). Then write `out/<project>/beats.json` following that arc: **beat-1 headline must be a ≤3s hook**; beat count per duration (30s→6–8, 60s→10–12); split each beat into **2 shots** (wide+detail) with **per-shot `camera_move` VARIED across adjacent beats** (never repeat; `static` on the payoff) and **rich `element_motion`** (see step 4). Each beat: `narration`, `title_cn`/`title_en`, `scene`, `bg`, `feel`, `hook`. This draft is the **first mandatory approval gate** — show the user the beat map before generating (the aspect-routing approximation in step 4 is the other one). Examples in `examples/`.

2. **Pick the visual style (hybrid — do this BEFORE keyframes).** Do not reuse one house style for every topic. Read `references/prompt-guide.md` (§5 theme presets); pick 3–4 **theme presets** (`styles.THEME_PRESETS`: `american-retro`, `swiss-modern`, `punk-zine`, `soviet-constructivist`, `wpa-propaganda`, `70s-groovy`, `chinese-ink`, `atomic-age`, `newsprint-editorial`) that fit the topic's era/culture/tone — **or compose a custom theme** by mixing the prompt-guide dimensions (medium/era/palette/type/finish) when none fit. Match the topic, **not** the language (an English film on Chinese history should look Chinese). A theme bundles the whole LOOK layer (idiom+palette+type+finish+mood+motion). Run a bake-off and let the user pick by eye — AI proposes, the library is the quality floor, the human decides. Set the pick as `"theme"`: `python3 scripts/style_bakeoff.py out/<project> american-retro,swiss-modern,punk-zine,atomic-age` Set the chosen name as `"collage_style"` in beats.json (keyframes.py reads it).

3. **Keyframes (the collage look).** `python3 scripts/keyframes.py out/<project>` Generates one collage poster per beat/shot with **google/nano-banana-2/text-to-image**, headline text baked in. Compose prompts with the 5-part structure in `references/prompt-guide.md`. Verify each poster looks like a *real layered collage* before animating — re-roll cheap ($0.08) here rather than paying to animate a weak image.

4. **Motion.** `python3 scripts/clips.py out/<project>` Animates each poster with **google/gemini-omni-flash/image-to-video**. Two independent axes (see `references/beat-layer.md` §3, tested on our stack): • **`camera_move`** — ONE move per shot. Safe/default: `{static, push_in, pull_out, pan, tilt, parallax}`. **Bold/experimental** `{orbit, dolly_zoom, roll, whip}` are **available, not banned** — they can warp the flat art, so pair with `constraints: loose` and **re-roll**. Any custom phrase also passes through. • **`element_motion`** — where the energy lives; **AI writes it per beat