Skip to content
Back to search

vox-director

Turn one topic into a finished Vox-style paper-collage explainer/ad video — automated end to end on Atlas Cloud + ffmpeg. An agent skill.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alisa0808--vox-director/badge.svg)](/listings/alisa0808--vox-director)

HTML

<a href="/listings/alisa0808--vox-director"><img src="/api/listings/alisa0808--vox-director/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This is an **agent skill** — it works with any coding agent that can read a workflow and run scripts (Claude Code, Codex, …). Claude Code auto-discovers it as a skill; other agents read [`AGENTS.md`](AGENTS.md) → [`SKILL.md`](SKILL.md).

**Option A — from this repo:**

git clone https://github.com/Alisa0808/vox-director.git ~/.claude/skills/vox-director

**Option B — from the packaged skill:** download [`vox-director.skill`](vox-director.skill) and install it via your Claude skills UI.

Then set your Atlas Cloud API key (get one at [atlascloud.ai/console/api-keys](https://www.atlascloud.ai/console/api-keys?utm_source=github&utm_campaign=vox_director)):

export ATLASCLOUD_API_KEY="sk-..."

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 331 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: vox-director
  3. description: >
  4. Turn ONE topic into a finished Vox-style paper-collage explainer / ad video, end to end
  5. on the Atlas Cloud API + local ffmpeg — script, collage keyframes, motion, voice-over,
  6. music, captions, all automated. Use this whenever the user wants a "Vox style" video,
  7. a paper/torn-paper collage animation, a "motion collage", a narrated explainer or short
  8. ad built from AI-generated collage posters, a scrapbook-style tribute, or wants to turn
  9. a topic / product / person into a punchy narrated collage video — even if they don't say
  10. the word "Vox". Also use when reproducing Stav Zilber / rom1trs / Higgsfield-style collage
  11. ad workflows.
  12. Three input modalities: a topic (B-roll), a talking-head video (A-roll mode), or a single
  13. photo of a person/product anchored into the collage (C-roll mode).
  14. Triggers: "vox video", "collage video", "motion collage", "paper collage
  15. explainer", "make a collage ad", "turn this topic into a collage video", "turn my
  16. photo/this product shot into a collage video".
  17. ---
  18. # Vox Director
  19. Turn a one-line topic into a finished **Vox-style paper-collage video**: a bold, punchy,
  20. narrated explainer/ad where each beat is a torn-paper collage poster that comes alive, with
  21. voice-over, music and captions. Runs on **one Atlas Cloud API key** + local **ffmpeg**.
  22. The look is the modern editorial paper-collage popularized by Vox explainers and creators
  23. like Stav Zilber / rom1trs: hand-cut paper cut-outs, torn edges, tape, halftone dots,
  24. newspaper clippings, bold flat color per beat, big cut-out headlines.
  25. ## The core idea (read this first)
  26. The Vox collage look and the collage motion are **two different steps**:
  27. 1. **The look is born in the IMAGE step.** Each beat is a finished collage *poster* made by a
  28. text-to-image model. All the collage DNA (torn paper, cut-outs, halftone, bold color,
  29. headline text) lives in that image. If the image isn't a rich collage, nothing downstream
  30. will save it.
  31. 2. **The motion is added after.** By default an AI video model animates the whole poster (the
  32. "living poster" path — simple, automated). For dramatic *piece-by-piece* assembly you cut
  33. the poster into parts and drive them with the local keyframe engine (advanced path).
  34. Everything hinges on the prompts. **Before writing any image or video prompt, read
  35. `references/prompt-guide.md`** — it has the exact prompt structures that make the difference
  36. between "a real Vox collage" and "a moving PowerPoint".
  37. ## Prerequisites (check, don't skip)
  38. - `echo "${ATLASCLOUD_API_KEY:+set}"` — if empty, tell the user to set it (get one at
  39. https://www.atlascloud.ai/console/api-keys) and stop.
  40. - `command -v ffmpeg ffprobe` — required for assembly (`brew install ffmpeg` on macOS).
  41. - `python3 -c "import PIL"` — Pillow, for captions/watermark overlays.
  42. ## Standard workflow (topic → film)
  43. This is the default, most-automated path. Every stage is one script, all driven by a single
  44. `beats.json` per project under `out/<project>/`.
  45. 1. **Topic → beat map.** First **read `references/beat-layer.md`** (the story layer) and pick a
  46. narrative `arc` that fits the topic (`timeline` for history, `pas`/`bab` for ads,
  47. `how_it_works` for explainers, `man_in_hole` for transformations, …). Then write
  48. `out/<project>/beats.json` following that arc: **beat-1 headline must be a ≤3s hook**; beat
  49. count per duration (30s→6–8, 60s→10–12); split each beat into **2 shots** (wide+detail) with
  50. **per-shot `camera_move` VARIED across adjacent beats** (never repeat; `static` on the payoff)
  51. and **rich `element_motion`** (see step 4). Each beat: `narration`, `title_cn`/`title_en`,
  52. `scene`, `bg`, `feel`, `hook`. This draft is the **first mandatory approval gate** — show the
  53. user the beat map before generating (the aspect-routing approximation in step 4 is the other
  54. one). Examples in `examples/`.
  55. 2. **Pick the visual style (hybrid — do this BEFORE keyframes).** Do not reuse one house style
  56. for every topic. Read `references/prompt-guide.md` (§5 theme presets); pick 3–4 **theme presets**
  57. (`styles.THEME_PRESETS`: `american-retro`, `swiss-modern`, `punk-zine`,
  58. `soviet-constructivist`, `wpa-propaganda`, `70s-groovy`, `chinese-ink`, `atomic-age`,
  59. `newsprint-editorial`) that fit
  60. the topic's era/culture/tone — **or compose a custom theme** by mixing the prompt-guide dimensions
  61. (medium/era/palette/type/finish) when none fit. Match the topic, **not** the language (an
  62. English film on Chinese history should look Chinese). A theme bundles the whole LOOK layer
  63. (idiom+palette+type+finish+mood+motion). Run a bake-off and let the user pick by eye — AI
  64. proposes, the library is the quality floor, the human decides. Set the pick as `"theme"`:
  65. `python3 scripts/style_bakeoff.py out/<project> american-retro,swiss-modern,punk-zine,atomic-age`
  66. Set the chosen name as `"collage_style"` in beats.json (keyframes.py reads it).
  67. 3. **Keyframes (the collage look).** `python3 scripts/keyframes.py out/<project>`
  68. Generates one collage poster per beat/shot with **google/nano-banana-2/text-to-image**,
  69. headline text baked in. Compose prompts with the 5-part structure in
  70. `references/prompt-guide.md`. Verify each poster looks like a *real layered collage*
  71. before animating — re-roll cheap ($0.08) here rather than paying to animate a weak image.
  72. 4. **Motion.** `python3 scripts/clips.py out/<project>`
  73. Animates each poster with **google/gemini-omni-flash/image-to-video**. Two independent axes
  74. (see `references/beat-layer.md` §3, tested on our stack):
  75. • **`camera_move`** — ONE move per shot. Safe/default: `{static, push_in, pull_out, pan, tilt,
  76. parallax}`. **Bold/experimental** `{orbit, dolly_zoom, roll, whip}` are **available, not
  77. banned** — they can warp the flat art, so pair with `constraints: loose` and **re-roll**.
  78. Any custom phrase also passes through.
  79. • **`element_motion`** — where the energy lives; **AI writes it per beat to fit that scene** (not a
  80. template). Make it RICH (several elements moving) — be bold. A **hero element flying across
  81. the frame** (paper bird/plane/coins) is a great **occasional** punch on a key beat, **not
  82. every shot** (a flyer in every frame reads as a formula).
  83. `motion_style` = amplitude `calm | punchy | max` (the theme sets a default). **`constraints`**
  84. = `strict` (default: defect guards on — flat-2D, one-way, no-morph; best for clean text-heavy
  85. explainers) or `loose` (let the model explore 3D/bold moves; re-roll the misses). **Headline
  86. text is hard-protected only on shots that have a title** (detail shots without a headline are
  87. free to go wild). For **real people / brand logos**, Omni & Seedance refuse — set
  88. `"video_model": "kwaivgi/kling-video-o3-pro/image-to-video"`.
  89. **Aspect routing** (`styles.resolve_video_aspect`, second approval gate): `clips.py` resolves
  90. `doc["aspect"]` against the chosen `video_model`'s own supported ratios — exact match wins;
  91. Omni is 16:9/9:16 only, Kling reference-to-video adds 1:1, Kling image-to-video/video-edit and
  92. Seedance just follow the input/ratio param. When there's no exact match it picks the nearest
  93. ratio but **stops and asks you to confirm** (set `"aspect_approx_confirmed": true` once you
  94. have) rather than silently reframing the film — every clip in one run shares the same resolved
  95. aspect so the finished film is never mixed.
  96. 5. **Voice + music.** `python3 scripts/audio.py out/<project>`
  97. One consistent narrator via **xai/tts-v1** + instrumental BGM via **minimax/music-2.6**.
  98. **Pick `voice_id` to fit the topic + language** (don't just keep the default) — see
  99. `references/voices.md` for the full roster (5 multilingual + ~66 native voices by language,
  100. with gender). Default `leo` (male, documentary). To narrate in a REAL person's own voice
  101. (the presenter of a C-roll photo, a brand voice), set `voice.clone_ref` to a local audio
  102. sample — narration switches to seed-audio voice cloning with a pinned-speaker,
  103. studio-clean template that keeps timing beat-stable (see gotchas: never hand seed-audio
  104. bare narration without that pin).
  105. 6. **Assemble.** `python3 scripts/assemble.py out/<project>`
  106. ffmpeg: normalize + concat all shots, lay the single narration ducked under the music,
  107. burn captions timed per beat, add the watermark. Output `out/<project>/final.mp4`.
  108. 7. **Verify.** You can't read an mp4 directly — extract frames to jpg and look:
  109. `ffmpeg -ss <t> -i final.mp4 -vf "scale=640:-1,format=yuvj420p" -frames:v 1 f.jpg`
  110. ### Cadence — how long shots should be
  111. A common mistake is one long shot per beat. On a 9:16 / social piece especially, a static
  112. 10s shot reads as dead air. Aim for a **cut every ~4–6 seconds**:
  113. - **Shots run 3–6s; never let a single shot exceed ~7s** — beyond that the AI motion has
  114. nowhere to go and it feels static.
  115. - **A beat's narration is ~8–10s, so give each beat 2 shots** (a *wide* establishing shot with
  116. the headline + a *detail* cut-in without it). The narration plays continuously across both;
  117. the visual cuts mid-sentence. This is the single biggest rhythm win.
  118. - So a ~60s film is typically **~6 beats × 2 shots × ~5s = 12 shots**, not 6 × 10s.
  119. - Reuse the wide keyframe as shot `a`; generate a tighter detail scene for shot `b`.
  120. `keyframes.py` skips any shot that already has a `keyframe_url`, so adding `b` shots and
  121. re-running only generates the new ones.
  122. Add a `shots` array to each beat (see schema). Give each shot its own short `scene` and
  123. `motion`; set `"title": true` only on the wide shot so the headline shows once per beat.
  124. ## A-roll mode (talking-head → collage)
  125. The standard workflow above is **B-roll**: a topic becomes AI-generated collage posters
  126. that get animated. **A-roll is the reverse case** — the user already has a real recorded
  127. talking-head video (a presenter speaking to camera) and wants it *itself* turned into the
  128. collage look, keeping their actual performance (face, lip movement, gestures) intact. There
  129. is no poster to generate; the "keyframe" is the presenter's own footage. Use A-roll when the
  130. user gives you a video file of themselves/a presenter talking, not a topic to write from
  131. scratch.
  132. 1. **Transcribe + auto-segment.** `python3 scripts/asr_beats.py <project_dir> <source.mp4>`
  133. Runs xai/stt-v1 on the source's own audio and cuts it into beats at sentence-ending
  134. punctuation or natural pause gaps (never exceeding ~9.5s, under Omni/Kling video-edit's
  135. 10s per-call cap). Writes `beats.json` with each beat's `start`/`end`/`text` — **this is
  136. the same mandatory approval gate as the B-roll beat map**: review it, set `"theme"` (run
  137. `style_bakeoff.py` the same way — the presenter's segment works fine as the bake-off
  138. source), and optionally fill in a `content_beats` string per beat (a sticker/stamp idea
  139. to layer in) before generating anything.
  140. 2. **Generate.** `python3 scripts/aroll_clips.py <project_dir> [only_ids]`
  141. Cuts each beat's time range out of the source, uploads it, and re-styles it with a
  142. **photographic paper-cutout sticker** treatment on the presenter — her real likeness,
  143. lip movement, eye-line and gestures follow the source frame-for-frame; only the
  144. silhouette edge and the world around her are paper-collage. Default model is
  145. `google/gemini-omni-flash/video-edit`; any beat it rejects automatically retries on
  146. `bytedance/seedance-2.0/reference-to-video` (set via `video_model`/`video_model_fallback`
  147. in beats.json). **Never ask the model to redraw or halftone-texture the face itself** —
  148. that gets rejected regardless of how the prompt is worded (tried both a strong and a
  149. softened phrasing; both failed). Uses the same aspect-routing confirm gate as `clips.py`.
  150. 3. **Assemble.** `python3 scripts/aroll_assemble.py <project_dir>`
  151. Muxes each generated clip with the *original* beat segment's own audio (never whatever
  152. audio the video model produced) so lip-sync is guaranteed regardless of which model
  153. handled that beat, normalizes every beat to one canvas, and concats into `final.mp4`.
  154. ## C-roll mode (one photo → collage)
  155. The third input modality — "cutout roll". A-roll re-styles a talking-head VIDEO; B-roll
  156. generates everything from a topic; **C-roll takes a single still PHOTO** (a selfie, an
  157. avatar card, a product shot) and anchors it inside the collage world: the subject is cut
  158. out as a PHOTOGRAPHIC sticker — never redrawn — and per-beat posters are generated around
  159. it with an image-EDIT model, then animated through the normal clip stage. Use C-roll when
  160. the user gives you one photo and a topic: a personal explainer fronted by their own face,
  161. or a collage ad built around a real product shot (validated on both, 2026-07-17).
  162. 1. **Beat map.** Same as B-roll (`references/beat-layer.md`, same approval gate), plus the
  163. C-roll fields in beats.json: `"mode": "croll"`, `"anchor_photo"`, `"croll_subject"`
  164. (`portrait` | `product`), and `subject_wardrobe` (portrait — lock the outfit or the
  165. paper-doll body drifts) or `subject_desc` (product). Set `"title": false` on shots —
  166. C-roll posters carry no headline; text belongs to captions. If there is no separate
  167. script, transcribe/derive narration first and let the audio's ASR timestamps define the
  168. beats (audio-first, like A-roll — not text-first like B-roll).
  169. 2. **Anchored keyframes.** `python3 scripts/croll_keyframes.py <project_dir>`
  170. Uploads the photo once and generates one anchored poster per shot via
  171. `google/nano-banana-2/edit` (fallback `openai/gpt-image-2/edit`). Portraits get a
  172. photographic face + illustrated paper-doll body; products get a pixel-faithful sticker
  173. with label typography intact. Prompt rules that are baked in (all three cost a re-run to
  174. learn): poses/expressions go to the BODY only — asking for a wink redraws the face;
  175. halftone must be scoped to the background or it bleeds onto skin; portrait clothing must
  176. be locked explicitly. The script also writes `anchor_freeze` into beats.json.
  177. 3. **Animate + audio + assemble.** Standard `clips.py` → `audio.py` → `assemble.py`.
  178. `clips.py` injects the `anchor_freeze` guard into every motion prompt — without it the
  179. video stage can re-letter a product label (observed: "PARFUM" → "PAREUM") or re-time a
  180. face. For narration in the subject's own voice, set `voice.clone_ref` (see Voice + music
  181. above); derive stamp/snap-zoom timing from the narration's ASR word timestamps
  182. (`asr_beats.py` works on any audio, not just A-roll footage).
  183. ## Host mode (a presenter speaks on camera)
  184. Use when the user wants a **digital presenter on screen** speaking some of the narration,
  185. from ONE still image of that presenter (not a recorded video: that is A-roll). Mark those
  186. beats with a shot `"kind": "host"`; every other beat stays normal B-roll. Full recipe,
  187. rules and limits: `references/host-mode.md` (read it before using this mode).
  188. 1. Add `host.avatar` (a finished character design, never redrawn) and, per host beat, one
  189. shot with `kind: "host"`, a world-only `scene` and an `element_motion` that names each
  190. element and pins its shape. The beat's narration must be at most 9.5 s.
  191. 2. `audio.py` first, then `python3 scripts/host_plates.py out/<project>`: **look at both
  192. plates** (flat green, face intact, empty region clear) before spending on video.
  193. 3. `python3 scripts/host_clips.py out/<project>` prints a cost estimate and stops; show it to
  194. the user, then re-run with `--yes`. It generates the presenter (Seedance) and the world
  195. (Omni) separately, adopts the presenter clip's own audio, and keys them together.
  196. 4. `clips.py` and `keyframes.py` skip host shots; `assemble.py` never stretches them.
  197. The user can place and size the presenter with `host.position` and `host.size`. 16:9 and
  198. 9:16 are supported. A host clip costs about twice a B-roll clip per second. Known issue:
  199. the world video can drift (see the reference); re-roll it if it does.
  200. ## beats.json schema
  201. ```json
  202. {
  203. "project": "my-film", "topic": "...", "language": "en",
  204. "aspect": "9:16", // 16:9 | 9:16 | 1:1 | 3:4
  205. "style": "collage",
  206. "provider": "atlas_cloud", // media backend — default; pluggable (scripts/provider.py)
  207. "theme": "american-retro", // THEME_PRESET (styles.THEME_PRESETS) — the LOOK layer
  208. "arc": "timeline", // narrative arc (beat-layer.md) — the STORY skeleton
  209. "video_model": "google/gemini-omni-flash/image-to-video", // Kling for real people
  210. "image_model": "google/nano-banana-2/text-to-image", // keyframes; or openai/gpt-image-2/text-to-image
  211. "image_resolution": "1k", // 1k (default) | 2k | 4k
  212. "video_resolution": "720p", // 720p (default); Seedance also 480p/1080p (Omni is 720p-only)
  213. "motion_style": "punchy", // amplitude: calm | punchy | max (theme sets a default)
  214. "constraints": "strict", // strict = defect guards on | loose = let AI explore + re-roll
  215. "voice": {"voice_id": "leo", "language": "en", "speed": 1.0}, // pick per topic/language — see references/voices.md
  216. // + optional "clone_ref": "path/to/sample.mp3" (clone that voice via seed-audio)
  217. // and "persona": "YouTube tutorial creator" (delivery style for cloned VO)
  218. "music": "epic cinematic orchestral, instrumental, no vocals",
  219. "mix": {"music": 0.6, "voice": 1.25}, // audio balance — optional; these are the defaults (BGM ducks under the VO)
  220. "caption_style": "white", // white (default: clean white subtitle) | paper (cream cut-out collage look)
  221. "captions": true, // false = no burned-in captions (deliver clean, subtitle in post)
  222. "watermark": "Made with Atlas Cloud",
  223. "host": {"avatar": "path/to/presenter.jpg", "position": "left", "size": 0.25}, // host mode only (references/host-mode.md)
  224. "mode": "croll", // C-roll only — plus the four fields below
  225. "anchor_photo": "path/to/photo.png", // C-roll: the still to anchor (person or product)
  226. "croll_subject": "portrait", // C-roll: portrait | product
  227. "subject_wardrobe": "a cream knitted sweater and charcoal trousers", // C-roll portrait: outfit lock
  228. "subject_desc": "the perfume bottle", // C-roll product: short noun phrase for the sticker
  229. "beats": [
  230. {
  231. "id": 1, "title_cn": "", "title_en": "BEFORE MONEY",
  232. "bg": "earthy clay tan", "feel": "ancient, humble", "hook": "surprising_stat",
  233. "narration": "For most of history, there was no money...",
  234. "shots": [
  235. // shot_size: EST_WIDE|WIDE|MEDIUM|CLOSE|DETAIL ; camera_move: static|push_in|
  236. // pull_out|pan|tilt|parallax (flat-safe only) — VARY per adjacent beat, static for payoff
  237. {"id": "a", "dur": 5, "title": true, "shot_size": "WIDE", "camera_move": "push_in",
  238. "scene": "...wide establishing collage...",
  239. "element_motion": "traders gesture, goat bobs, a paper bird flaps across the frame, coins scatter"},
  240. {"id": "b", "dur": 5, "title": false, "shot_size": "CLOSE", "camera_move": "parallax",
  241. "scene": "...close cut-in detail...",
  242. "element_motion": "the exchanged goods slide together, halftone pulses"}
  243. ]
  244. }
  245. ]
  246. }
  247. ```
  248. `theme`+`arc` set the two big layers; `element_motion` per shot is the energy (make it rich — see
  249. below). `motion`/`collage_style`/`era` are still read for back-compat.
  250. ## Model selection (always verify IDs live)
  251. Model IDs change — fetch the live list first: `GET https://api.atlascloud.ai/api/v1/models`
  252. (no auth; keep only `display_console: true`). Defaults that work today:
  253. | Job | Model | Note |
  254. |---|---|---|
  255. | Keyframe / collage poster | `google/nano-banana-2/text-to-image` | default; renders CN+EN text well; `image_resolution` 1k/2k/4k |
  256. | Keyframe (alternative) | `openai/gpt-image-2/text-to-image` | set via `image_model`; size+quality auto-mapped from aspect+resolution |
  257. | Cut out an element | `youchuan/v8.1/remove-background` | advanced path only |
  258. | Animate (non-real content) | `google/gemini-omni-flash/image-to-video` | keeps text stable, layered motion |
  259. | Animate (**real people / brands**) | `kwaivgi/kling-video-o3-pro/image-to-video` | Omni & Seedance BLOCK celebrities |
  260. | Narration | `xai/tts-v1` | clean, multilingual, `voice_id` |
  261. | Music | `minimax/music-2.6` | `is_instrumental: true` |
  262. See `references/models-and-gotchas.md` for the full model-choice reasoning and every
  263. API / ffmpeg gotcha (auth header, curl downloads, no-libass captions, content blocks, etc.).
  264. Read it before debugging any failure — most failures are already documented there.
  265. **Backends are pluggable.** Every API call goes through a **provider** (`scripts/provider.py`);
  266. Atlas Cloud is the default and only backend today. Set `"provider"` in beats.json to route to a
  267. different backend once one is added — the stage scripts don't change. `scripts/provider.py`'s
  268. `run_jobs()` also does the submit/poll with **auto-resubmit on a stalled or failed job**.
  269. ## Advanced: element-level motion collage
  270. The standard path animates the *whole* poster (great, automated, "living poster"). For the
  271. dramatic **pieces-fly-in-and-assemble** motion collage (à la cr7v2), or to animate **real
  272. people with full control and zero content filters**, cut each poster into independent
  273. elements and drive them with the local keyframe engine (no video model needed).
  274. Read `references/local-engine.md`. In short: `extract_elements.py` (crop + background-removal
  275. + residue/erase cleanup) → `motion.py` (Layer + keyframes, `fly_in`/`slap`/`drop`/`pop_settle`
  276. easings, procedural confetti/starburst, camera zoom+shake+whip, frame render). Pieces fly
  277. back to their **original positions** on a blurred-placeholder backdrop, so the assembled
  278. frame reconstructs the original poster.
  279. ## Editions
  280. - **Auto edition** (this skill): topic in, film out, all on Atlas.
  281. - **Manual prompt-pack**: if the user isn't on Atlas, just produce the beat map + the per-beat
  282. image prompts + the per-clip motion prompts + the narration script for them to paste into
  283. any generator. The creative engine (the prompts) is identical.
README.md · README · 146 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="right"><b>English</b> · <a href="README.zh.md">简体中文</a></p>
  2. # 🎬 Vox Director
  3. **Turn one topic into a finished Vox-style paper-collage explainer / ad video — script, collage keyframes, motion, voice-over, music and captions, all automated.**
  4. An **agent skill** that runs end to end on the [Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_campaign=vox_director) API + local `ffmpeg`, usable by any coding agent (Claude Code, Codex, etc.). You give it a one-line topic; it gives you an `mp4`.
  5. ![License: MIT](https://img.shields.io/badge/License-MIT-black.svg) ![Powered by Atlas Cloud](https://img.shields.io/badge/powered%20by-Atlas%20Cloud-ff5a1f.svg) ![Agent Skill](https://img.shields.io/badge/Agent-Skill-d97757.svg)
  6. <div align="center">
  7. https://github.com/user-attachments/assets/ed08d230-7bcb-4b48-a17d-23c079208f9f
  8. <b>▶ "The evolution of Chinese civilization" · 30s</b>
  9. </div>
  10. <table>
  11. <tr>
  12. <td width="25%"><a href="https://github.com/user-attachments/assets/216cd62f-6314-456c-94cf-1090b8559a22"><img src="assets/thumbs/football.jpg" width="100%" alt="How football conquered the world"></a></td>
  13. <td width="25%"><a href="https://github.com/user-attachments/assets/561788b1-5615-4828-b3f8-b24ae5ad7bcd"><img src="assets/thumbs/mexican.jpg" width="100%" alt="Mexican street food"></a></td>
  14. <td width="25%"><a href="https://github.com/user-attachments/assets/f69f072f-f50a-41ba-9e66-7ed0aae4ddc0"><img src="assets/thumbs/money.jpg" width="100%" alt="A brief history of money"></a></td>
  15. <td width="25%"><a href="https://github.com/user-attachments/assets/b9ff526f-577f-4acb-aafe-a2519a9b7c1c"><img src="assets/thumbs/silicon-valley.jpg" width="100%" alt="A brief history of Silicon Valley"></a></td>
  16. </tr>
  17. <tr>
  18. <td align="center"><sub>Football history · 60s</sub></td>
  19. <td align="center"><sub>Mexican street food · 60s</sub></td>
  20. <td align="center"><sub>A brief history of money · 60s</sub></td>
  21. <td align="center"><sub>Silicon Valley history · 60s</sub></td>
  22. </tr>
  23. </table>
  24. <p align="center"><sub><em>▶ more films — click any thumbnail to play</em></sub></p>
  25. ---
  26. ## What it is
  27. The look is the modern editorial **paper-collage** popularized by Vox explainers: hand-cut paper cut-outs, torn edges, tape, halftone dots, newspaper clippings, bold flat color per beat, big cut-out headlines — brought to life with motion, a narrator, music and captions.
  28. ## How it works
  29. One topic flows through one script per stage, all driven by a single `beats.json` per project:
  30. ```
  31. topic
  32. │
  33. ├─ 1. beat map pick a narrative arc → write beats.json ◀── GATE 1: you approve the beat map
  34. ├─ 2. style bake-off render the same beat in 3–4 themes ◀── GATE 2: you pick the look by eye
  35. ├─ 3. keyframes one collage poster per beat (nano-banana-2)
  36. ├─ 4. motion animate each poster (gemini-omni-flash i2v)
  37. ├─ 5. voice + music one narrator (xai/tts) + BGM (minimax/music)
  38. ├─ 6. assemble ffmpeg: concat, duck music under VO, burn captions + watermark
  39. └─ final.mp4
  40. ```
  41. That flow is **B-roll** — a topic in, everything generated. Two more input modalities, plus a presenter mode, reuse the same engine:
  42. - **A-roll — you already have a talking-head video.** It is ASR-segmented into beats and re-styled into the collage look, keeping the real face, lip-sync and gestures frame-for-frame (`gemini-omni-flash/video-edit`, auto-retrying on `seedance-2.0/reference-to-video`).
  43. - **C-roll — you have one still photo** (a selfie, a product shot). The subject is cut out as a photographic sticker — never redrawn — and each beat's poster is generated around it (`nano-banana-2/edit`). The narration can be cloned into the subject's own voice.
  44. - **Host — one image of a presenter.** Selected beats cut to a digital presenter who speaks the narration, lip-synced, inside the collage world (16:9 and 9:16; position and size adjustable). The presenter and the world are generated as two plates and keyed together (`seedance-2.0/reference-to-video` + `gemini-omni-flash/image-to-video`).
  45. Two ideas make or break the result, and the skill is built around both:
  46. 1. **The look is born in the image step.** Each beat is a finished collage *poster*. All the collage DNA (torn paper, cut-outs, halftone, headline text) lives in that image — if the poster isn't a rich collage, nothing downstream saves it.
  47. 2. **The motion is added after.** By default an AI video model animates the whole poster (the "living poster" path). For dramatic *piece-by-piece* assembly, an optional local keyframe engine cuts the poster into parts and drives them frame-by-frame (no content filters, pixel-exact — great for real people).
  48. Two human decision gates keep you in control (approve the beat map; pick the style); everything else is automated.
  49. ## Models (verified on Atlas Cloud)
  50. | Job | Model |
  51. |---|---|
  52. | Keyframe / collage poster | `google/nano-banana-2/text-to-image` |
  53. | Animate (non-real content) | `google/gemini-omni-flash/image-to-video` |
  54. | Animate (**real people / brands**) | `kwaivgi/kling-video-o3-pro/image-to-video` |
  55. | Re-style a talking-head (A-roll) | `google/gemini-omni-flash/video-edit` |
  56. | Anchor a photo in the collage (C-roll) | `google/nano-banana-2/edit` |
  57. | Presenter on camera (Host) | `bytedance/seedance-2.0/reference-to-video` + `google/gemini-omni-flash/image-to-video` |
  58. | Narration | `xai/tts-v1` |
  59. | Narration in a real person's voice | `bytedance/seed-audio-1.0` (voice cloning) |
  60. | Music | `minimax/music-2.6` |
  61. | Cut out an element (advanced path) | `youchuan/v8.1/remove-background` |
  62. Model IDs drift — the skill fetches the live list from `GET https://api.atlascloud.ai/api/v1/models` before running.
  63. ## Install
  64. This is an **agent skill** — it works with any coding agent that can read a workflow and run scripts (Claude Code, Codex, …). Claude Code auto-discovers it as a skill; other agents read [`AGENTS.md`](AGENTS.md) → [`SKILL.md`](SKILL.md).
  65. **Option A — from this repo:**
  66. ```bash
  67. git clone https://github.com/Alisa0808/vox-director.git ~/.claude/skills/vox-director
  68. ```
  69. **Option B — from the packaged skill:** download [`vox-director.skill`](vox-director.skill) and install it via your Claude skills UI.
  70. Then set your Atlas Cloud API key (get one at [atlascloud.ai/console/api-keys](https://www.atlascloud.ai/console/api-keys?utm_source=github&utm_campaign=vox_director)):
  71. ```bash
  72. export ATLASCLOUD_API_KEY="sk-..."
  73. ```
  74. ## Quick start
  75. Just ask your coding agent, with the skill installed:
  76. > *"Make me a Vox-style collage video introducing Mexican street food — English, 16:9, 15 seconds."*
  77. The agent will draft a beat map for your approval, run a style bake-off for you to pick from, then generate keyframes → motion → voice → music and assemble `out/<project>/final.mp4`.
  78. ## Requirements
  79. - A **coding agent** — Claude Code, Codex, or similar
  80. - **Atlas Cloud** API key
  81. - **ffmpeg** + **ffprobe** (`brew install ffmpeg`)
  82. - **Python 3** with **Pillow** (`pip install pillow`) — for caption/watermark overlays
  83. ## What's in the box
  84. ```
  85. SKILL.md the skill (English) — the workflow the agent follows
  86. SKILL.zh.md the same skill in Chinese
  87. AGENTS.md entry point for non-Claude agents (Codex, …)
  88. references/ the creative engine
  89. prompt-guide.md the LOOK layer — prompt structures, vocab & 9 theme presets
  90. beat-layer.md 14 narrative arcs + hook/pacing + shot patterns
  91. voices.md xai/tts voice roster — pick a voice_id per language/tone
  92. models-and-gotchas.md every API / ffmpeg gotcha, already solved
  93. local-engine.md the advanced element-level motion engine
  94. scripts/ one script per pipeline stage
  95. examples/ ready-to-run beats.json examples
  96. assets/ the showcase film
  97. ```
  98. ## Credits
  99. Built by **[@alisaqqt](https://x.com/alisaqqt)** — follow for more agent-skill experiments.
  100. Inspired by the collage-ad workflows of **[Stav Zilber](https://x.com/StavZilber)**, **[rom1trs](https://x.com/rom1trs)** and **[Higgsfield](https://x.com/higgsfield_ai)**, and by **[Vox](https://www.vox.com)**'s explainer visual language.
  101. Built end to end on **[Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_campaign=vox_director)** — one prompt, one film.
  102. ## License
  103. [MIT](LICENSE) © 2026 Alisa Qian

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.