# 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. **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 **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 make it move. ## 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. ## What's actually in the repo - `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. ## References - Source code: https://github.com/Alisa0808/vox-director - The underlying API: https://www.atlascloud.ai - Maker: [Alisa Qian (@alisaqqt)](https://x.com/alisaqqt) - The explainer visual language it imitates: https://www.vox.com ## Related - [[AI Agent Skills]] - [[Claude Code]] - [[Codex CLI]] - [[FFmpeg]] - [[Nano Banana]] - [[Gemini]] - [[Voice Cloning]] - [[Python]] - [[Open Source]] - [[MIT License]]