# Vox Director Vox Director turns a one-line topic into a finished Vox-style paper-collage explainer video. Script, keyframes, motion, narration, music and captions, all generated. By Alisa Qian (`@alisaqqt`), [[MIT License]], Python. The important structural fact: **it is not an application, it's an [[AI Agent Skills|agent skill]]**. There's no binary and no service. It's a `SKILL.md`, a set of reference documents and a handful of scripts that any coding agent can read and execute. [[Claude Code]] auto-discovers it; [[Codex CLI]] and others enter through `AGENTS.md`. You install it by cloning into `~/.claude/skills/vox-director`, set an Atlas Cloud API key, and then simply ask: > *"Make me a Vox-style collage video introducing Mexican street food, English, 16:9, 15 seconds."* ## The pipeline Everything flows from one `beats.json` per project, one script per stage: 1. **Beat map** — pick a narrative arc, write `beats.json` — **gate 1: you approve it** 2. **Style bake-off** — render the same beat in 3-4 themes — **gate 2: you pick the look by eye** 3. **Keyframes** — one collage poster per beat 4. **Motion** — animate each poster 5. **Voice and music** — one narrator plus a backing track 6. **Assemble** — [[FFmpeg]] concatenates, ducks the music under the voice-over, burns in captions and watermark Two human decision gates, everything else automated. Those gates are placed exactly where taste can't be delegated and a wrong call is expensive to discover later. ## The two ideas it's built on These are stated plainly in the README and they're the transferable part: **The look is born in the image step.** Each beat is a finished collage *poster*. All the collage DNA lives in that single image: torn paper, cut-outs, halftone dots, headline type. If the poster isn't a rich collage, nothing downstream saves it. **The motion is added after.** By default a video model animates the whole poster, the "living poster" path. For piece-by-piece assembly there's an optional local keyframe engine that cuts the poster into parts and drives them frame by frame, which is pixel-exact and dodges content filters. Get the still right, then move it. That ordering is the whole method. ## Three input modes The same engine accepts three starting points: - **B-roll** — a topic goes in, everything is generated. The default. - **A-roll** — you already have a talking-head video. It's ASR-segmented into beats and re-styled into the collage look, keeping the real face, lip-sync and gestures frame for frame. - **C-roll** — you have one still photo, a selfie or a product shot. The subject is cut out as a photographic sticker, never redrawn, and each beat's poster is generated around it. Narration can be cloned into that person's own voice. ## Models Everything runs on the Atlas Cloud API plus local `ffmpeg`. | Job | Model | |---|---| | Collage poster | `google/nano-banana-2/text-to-image` | | Animate (non-real content) | `google/gemini-omni-flash/image-to-video` | | Animate (real people, brands) | `kwaivgi/kling-video-o3-pro/image-to-video` | | Re-style a talking head (A-roll) | `google/gemini-omni-flash/video-edit` | | Anchor a photo (C-roll) | `google/nano-banana-2/edit` | | Narration | `xai/tts-v1` | | Narration in a real voice | `bytedance/seed-audio-1.0` | | Music | `minimax/music-2.6` | | Background removal | `youchuan/v8.1/remove-background` | Model IDs drift, so the skill fetches the live list from the Atlas Cloud models endpoint before each run. A small detail that says a lot about how carefully this was built. ## What's actually in the repo The layout is the interesting bit, because it's a template for skill design: - `SKILL.md` and `SKILL.zh.md` — the workflow the agent follows, English and Chinese - `AGENTS.md` — entry point for non-Claude agents - `references/` — the creative engine: `prompt-guide.md` (prompt structures, vocabulary, 9 theme presets), `beat-layer.md` (14 narrative arcs, hook and pacing, shot patterns), `voices.md` (the voice roster), `models-and-gotchas.md` (every API and ffmpeg gotcha, pre-solved), `local-engine.md` - `scripts/` — one per pipeline stage - `examples/` — ready-to-run `beats.json` Requirements are modest: a coding agent, an Atlas Cloud key, `ffmpeg` and `ffprobe`, and Python with Pillow for the caption and watermark overlays. ## Why I keep this note Not for the collage aesthetic, which I have no use for. For the architecture. **This is the best example I've seen of a skill that carries genuine craft, not just instructions.** The `references/` folder is where the value sits: 14 narrative arcs, 9 theme presets, a prompt vocabulary, and a file of already-solved API gotchas. That's an expert's accumulated judgment, written down as files an agent reads. Most skills I write are procedure. This one is procedure *plus* taste, and the taste is the part that took real work. **The gate placement is worth copying.** Two human checkpoints, both early, both where judgment can't be automated: approve the structure, pick the look. Everything after is mechanical. That's the right shape for any expensive generative pipeline, because a bad call at stage one wastes every stage after it. **And it's a reminder that a skill can be a product.** No app, no hosting, no sign-up. A folder of Markdown and scripts, distributed by `git clone`, that produces a finished mp4. Worth remembering the next time I think something needs to be an app before it can be useful. ## References - [Alisa0808/vox-director](https://github.com/Alisa0808/vox-director) — source - [Atlas Cloud](https://www.atlascloud.ai/) — the API everything runs on - [Atlas Cloud API keys](https://www.atlascloud.ai/console/api-keys) - [Alisa Qian (@alisaqqt)](https://x.com/alisaqqt) — author - [Vox](https://www.vox.com) — the explainer visual language it imitates ## Related - [[AI Agent Skills]] - [[Claude Code]] - [[Codex CLI]] - [[FFmpeg]] - [[Nano Banana]] - [[Gemini]] - [[Voice Cloning]] - [[Python]] - [[Open Source]] - [[MIT License]]