by Alisa0808
Turn one topic into a finished Vox-style paper-collage explainer/ad video — automated end to end on Atlas Cloud + ffmpeg. An agent skill.
# Add to your Claude Code skills
git clone https://github.com/Alisa0808/vox-directorLast scanned: 7/12/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-07-12T06:31:53.502Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}vox-director is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by Alisa0808. Turn one topic into a finished Vox-style paper-collage explainer/ad video — automated end to end on Atlas Cloud + ffmpeg. An agent skill. It has 1,539 GitHub stars.
Yes. vox-director passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/Alisa0808/vox-director" and add it to your Claude Code skills directory (see the Installation section above). vox-director ships a SKILL.md manifest, so compatible agents can discover and load it automatically.
vox-director is primarily written in Python. It is open-source under Alisa0808 on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh vox-director against similar tools.
No comments yet. Be the first to share your thoughts!
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
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 Vox collage look and the collage motion are two different steps:
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".
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.This is the default, most-automated path. Every stage is one script, all driven by a single
beats.json per project under out/<project>/.
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/.
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).
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.
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 to fit that scene (not a
template). Make it RICH (several elements moving) — be bold. A hero element flying across
the frame (paper bird/plane/coins) is a great occasional punch on a key beat, not
every shot (a flyer in every frame reads as a formula).
motion_style = amplitude calm | punchy | max (the theme sets a default). constraints
= strict (default: defect guards on — flat-2D, one-way, no-morph; best for clean text-heavy
explainers) or loose (let the model explore 3D/bold moves; re-roll the misses). Headline
text is hard-protected only on shots that have a title (detail shots without a headline are
free to go wild). For real people / brand logos, Omni & Seedance refuse — set
"video_model": "kwaivgi/kling-video-o3-pro/image-to-video".
Aspect routing (styles.resolve_video_aspect, second approval gate): clips.py resolves
doc["aspect"] against the chosen video_model's own supported ratios — exact match wins;
Omni is 16:9/9:16 only, Kling reference-to-video adds 1:1, Kling image-to-video/video-edit and
Seedance just follow the input/ratio param. When there's no exact match it picks the nearest
ratio but stops and asks you to confirm (set "aspect_approx_confirmed": true once you
have) rather than silently reframing the film — every clip in one run shares the same resolved
aspect so the finished film is never mixed.
Voice + music. python3 scripts/audio.py out/<project>
One consistent narrator via xai/tts-v1 + instrumental BGM via minimax/music-2.6.
Pick voice_id to fit the topic + language (don't just keep the default) — see
references/voices.md for the full roster (5 multilingual + ~66 native voices by language,
with gender). Default leo (male, documentary). To narrate in a REAL person's own voice
(the presenter of a C-roll photo, a brand voice), set voice.clone_ref to a local audio
sample — narration switches to seed-audio voice cloning with a pinned-speaker,
studio-clean template that keeps timing beat-stable (see gotchas: never hand seed-audio
bare narration without that pin).
Assemble. python3 scripts/assemble.py out/<project>
ffmpeg: normalize + concat all shots, lay the single narration ducked under the music,
burn captions timed per beat, add the watermark. Output out/<project>/final.mp4.
Verify. You can't read an mp4 directly — extract frames to jpg and look:
ffmpeg -ss <t> -i final.mp4 -vf "scale=640:-1,format=yuvj420p" -frames:v 1 f.jpg
A common mistake is one long shot per beat. On a 9:16 / social piece especially, a static 10s shot reads as dead air. Aim for a cut every ~4–6 seconds:
a; generate a tighter detail scene for shot b.
keyframes.py skips any shot that already has a keyframe_url, so adding b shots and
re-running only generates the new ones.Add a shots array to each beat (see schema). Give each shot its own short scene and
motion; set "title": true only on the wide shot so the headline shows once per beat.
The standard workflow above is B-roll: a topic becomes AI-generated collage posters that get animated. A-roll is the reverse case — the user already has a real recorded talking-head video (a presenter speaking to camera) and wants it itself turned into the collage look, keeping their actual performance (face, lip movement, gestures) intact. There is no poster to generate; the "keyframe" is the presenter's own footage. Use A-roll when the user gives you a video file of themselves/a presenter talking, not a topic to write from scratch.
Transcribe + auto-segment. python3 scripts/asr_beats.py <project_dir> <source.mp4>
Runs xai/stt-v1 on the source's own audio and cuts it into beats at sentence-ending
punctuation or natural pause gaps (never exceeding ~9.5s, under Omni/Kling video-edit's
10s per-call cap). Writes beats.json with each beat's start/end/text — this is
the same mandatory approval gate as the B-roll beat map: review it, set "theme" (run
style_bakeoff.py the same way — the presenter's segment works fine as the bake-off
source), and optionally fill in a content_beats string per beat (a sticker/stamp idea
to layer in) before generating anything.
Generate. python3 scripts/aroll_clips.py <project_dir> [only_ids]
Cuts each beat's time range out of the source, uploads it, and re-styles it with a
photographic paper-cutout sticker treatment on the presenter — her real likeness,
lip movement, eye-line and gestures follow the source frame-for-frame; only the
silhouette edge and the world around her are paper-collage. Default model is
google/gemini-omni-flash/video-edit; any beat it rejects automatically retries on
bytedance/seedance-2.0/reference-to-video (set via video_model/video_model_fallback
in beats.json). Never ask the model to redraw or halftone-texture the face itself —
that gets rejected regardless of how the prompt is worded (tried both a strong and a
softened phrasing; both failed). Uses the same aspect-routing confirm gate as clips.py.
Assemble. python3 scripts/aroll_assemble.py <project_dir>
Muxes each generated clip with the original beat segment's own audio (never whatever
audio the video model produced) so lip-sync is guaranteed regardless of which model
handled that beat, normalizes every beat to one canvas, and concats into final.mp4.
The third input modality — "cutout roll". A-roll re-styles a talking-head VIDEO; B-roll generates everything from a topic; C-roll takes a single still PHOTO (a selfie, an avatar card, a product shot) and anchors it inside the collage world: the subject is cut out as a PHOTOGRAPHIC sticker — never redrawn — and per-beat posters are generated around it with an image-EDIT model, then animated through the normal clip stage. Use C-roll when the user gives you one photo and a topic: a personal explainer fronted by their own face, or a collage ad built around a real product shot (validated on both, 2026-07-17).
Beat map. Same as B-roll (references/beat-layer.md, same approval gate), plus the
C-roll fields in beats.json: "mode": "croll", "anchor_photo", "croll_subject"
(portrait | product), and subject_wardrobe (portrait — lock the outfit or the
paper-doll body drifts) or subject_desc (product). Set "title": false on shots —
C-roll posters carry no headline; text belongs to captions. If there is no separate
script, transcribe/derive narration first and let the audio's ASR timestamps define the
beats (audio-first, like A-roll — not text-first like B-roll).
Anchored keyframes. python3 scripts/croll_keyframes.py <project_dir>
Uploads the photo once and generates one anchored poster per shot via
google/nano-banana-2/edit (fallback openai/gpt-image-2/edit). Portraits get a
photographic face + illustrated paper-doll body; products get a pixel-faithful sticker
with label typography intact. Prompt rules that are baked in (all three cost a re-run to
learn): poses/expressions go to the BODY only — asking for a wink redraws the face;
halftone must be scoped to the background or it bleeds onto skin; portrait clothing must
be locked explicitly. The script also writes anchor_freeze into beats.json.
Animate + audio + assemble. Standard clips.py → audio.py → assemble.py.
clips.py injects the anchor_freeze guard into every motion prompt — without it the
video stage can re-letter a product label (observed: "PARFUM" → "PAREUM") or re-time a
face. For narration in the subject's own voice, set voice.clone_ref (see Voice + music
above); derive stamp/snap-zoom timing from the narration's ASR word timestamps
(asr_beats.py works on any audio, not just A-roll footage).
{
"project": "my-film", "topic": "...", "language": "en",
"aspect": "9:16", // 16:9 | 9:16 | 1:1 | 3:4
"style": "collage",
"provider": "atlas_cloud", // media backend — default; pluggable (scripts/provider.py)
"theme": "american-retro", // THEME_PRESET (styles.THEME_PRESETS) — the LOOK layer
"arc": "timeline", // narrative arc (beat-layer.md) — the STORY skeleton
"video_model": "google/gemini-omni-flash/image-to-video", // Kling for real people
"image_model": "google/nano-banana-2/text-to-image", // keyframes; or openai/gpt-image-2/text-to-image
"image_resolution": "1k", // 1k (default) | 2k | 4k
"video_resolution": "720p", // 720p (default); Seedance also 480p/1080p (Omni is 720p-only)
"motion_style": "punchy", // amplitude: calm | punchy | max (theme sets a default)
"constraints": "strict", // strict = defect guards on | loose = let AI explore + re-roll
"voice": {"voice_id": "leo", "language": "en", "speed": 1.0}, // pick per topic/language — see references/voices.md
// + optional "clone_ref": "path/to/sample.mp3" (clone that voice via seed-audio)
// and "persona": "YouTube tutorial creator" (delivery style for cloned VO)
"music": "epic cinematic orchestral, instrumental, no vocals",
"mix": {"music": 0.6, "voice": 1.25}, // audio balance — optional; these are the defaults (BGM ducks under the VO)
"caption_style": "white", // white (default: clean white subtitle) | paper (cream cut-out collage look)
"captions": true, // false = no burned-in captions (deliver clean, subtitle in post)
"watermark": "Made with Atlas Cloud",
"mode": "croll", // C-roll only — plus the four fields below
"anchor_photo": "path/to/photo.png", // C-roll: the still to anchor (person or product)
"croll_subject": "portrait", // C-roll: portrait | product
"subject_wardrobe": "a cream knitted sweater and charcoal trousers", // C-roll portrait: outfit lock
"subject_desc": "the perfume bottle", // C-roll product: short noun phrase for the sticker
"beats": [
{
"id": 1, "title_cn": "", "title_en": "BEFORE MONEY",
"bg": "earthy clay tan", "feel": "ancient, humble", "hook": "surprising_stat",
"narration": "For most of history, there was no money...",
"shots": [
// shot_size: EST_WIDE|WIDE|MEDIUM|CLOSE|DETAIL ; camera_move: static|push_in|
// pull_out|pan|tilt|parallax (flat-safe only) — VARY per adjacent beat, static for payoff
{"id": "a", "dur": 5, "title": true, "shot_size": "WIDE", "camera_move": "push_in",
"scene": "...wide establishing collage...",
"element_motion": "traders gesture, goat bobs, a paper bird flaps across the frame, coins scatter"},
{"id": "b", "dur": 5, "title": false, "shot_size": "CLOSE", "camera_move": "parallax",
"scene": "...close cut-in detail...",
"element_motion": "the exchanged goods slide together, halftone pulses"}
]
}
]
}
theme+arc set the two big layers; element_motion per shot is the energy (make it rich — see
below). motion/collage_style/era are still read for back-compat.
Model IDs change — fetch the live list first: GET https://api.atlascloud.ai/api/v1/models
(no auth; keep only display_console: true). Defaults that work today:
| Job | Model | Note |
|---|---|---|
| Keyframe / collage poster | google/nano-banana-2/text-to-image |
default; renders CN+EN text well; image_resolution 1k/2k/4k |
| Keyframe (alternative) | openai/gpt-image-2/text-to-image |
set via image_model; size+quality auto-mapped from aspect+resolution |
| Cut out an element | youchuan/v8.1/remove-background |
advanced path only |
| Animate (non-real content) | google/gemini-omni-flash/image-to-video |
keeps text stable, layered motion |
| Animate (real people / brands) | kwaivgi/kling-video-o3-pro/image-to-video |
Omni & Seedance BLOCK celebrities |
| Narration | xai/tts-v1 |
clean, multilingual, voice_id |
| Music | minimax/music-2.6 |
is_instrumental: true |
See references/models-and-gotchas.md for the full model-choice reasoning and every
API / ffmpeg gotcha (auth header, curl downloads, no-libass captions, content blocks, etc.).
Read it before debugging any failure — most failures are already documented there.
Backends are pluggable. Every API call goes through a provider (scripts/provider.py);
Atlas Cloud is the default and only backend today. Set "provider" in beats.json to route to a
different backend once one is added — the stage scripts don't change. scripts/provider.py's
run_jobs() also does the submit/poll with auto-resubmit on a stalled or failed job.
The standard path animates the whole poster (great, automated, "living poster"). For the dramatic pieces-fly-in-and-assemble motion collage (à la cr7v2), or to animate real people with full control and zero content filters, cut each poster into independent elements and drive them with the local keyframe engine (no video model needed).
Read references/local-engine.md. In short: extract_elements.py (crop + background-removal
motion.py (Layer + keyframes, fly_in/slap/drop/pop_settle
easings, procedural confetti/starburst, camera zoom+shake+whip, frame render). Pieces fly
back to their original positions on a blurred-placeholder backdrop, so the assembled
frame reconstructs the original poster.Turn one topic into a finished Vox-style paper-collage explainer / ad video — script, collage keyframes, motion, voice-over, music and captions, all automated.
An agent skill that runs end to end on the Atlas Cloud API + local ffmpeg, usable by any coding agent (Claude Code, Codex, etc.). You give it a one-line topic; it gives you an mp4.
https://github.com/user-attachments/assets/ed08d230-7bcb-4b48-a17d-23c079208f9f
▶ "The evolution of Chinese civilization" · 30s
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.
One topic flows through one script per stage, all driven by a single beats.json per project:
topic
│
├─ 1. beat map pick a narrative arc → write beats.json ◀── GATE 1: you approve the beat map
├─ 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 (nano-banana-2)
├─ 4. motion animate each poster (gemini-omni-flash i2v)
├─ 5. voice + music one narrator (xai/tts) + BGM (minimax/music)
├─ 6. assemble ffmpeg: concat, duck music under VO, burn captions + watermark
└─ final.mp4
That flow is B-roll — a topic in, everything generated. Two more input modalities reuse the same engine:
gemini-omni-flash/video-edit, auto-retrying on seedance-2.0/reference-to-video).nano-banana-2/edit). The narration can be cloned into the subject's own voice.Two ideas make or break the result, and the skill is built around both:
Two human decision gates keep you in control (approve the beat map; pick the style); everything else is automated.
| Job | Model |
|---|---|
| Keyframe / 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 in the collage (C-roll) | google/nano-banana-2/edit |
| Narration | xai/tts-v1 |
| Narration in a real person's voice | bytedance/seed-audio-1.0 (voice cloning) |
| Music | minimax/music-2.6 |
| Cut out an element (advanced path) | youchuan/v8.1/remove-background |
Model IDs drift — the skill fetches the live list from GET https://api.atlascloud.ai/api/v1/models before running.
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 → 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 and install it via your Claude skills UI.
Then set your Atlas Cloud API key (get one at atlascloud.ai/console/api-keys):
export ATLASCLOUD_API_KEY="sk-..."
Just ask your coding agent, with the skill installed:
"Make me a Vox-style collage video introducing Mexican street food — English, 16:9, 15 seconds."
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.
brew install ffmpeg)pip install pillow) — for caption/watermark overlaysSKILL.md the skill (English) — the workflow the agent follows
SKILL.zh.md the same skill in Chinese
AGENTS.md entry point for non-Claude agents (Codex, …)
references/ the creative engine
prompt-guide.md the LOOK layer — prompt structures, vocab & 9 theme presets
beat-layer.md 14 narrative arcs + hook/pacing + shot patterns
voices.md xai/tts voice roster — pick a voice_id per language/tone
models-and-gotchas.md every API / ffmpeg gotcha, already solved
local-engine.md the advanced element-level motion engine
scripts/ one script per pipeline stage
examples/ ready-to-run beats.json examples
assets/ the showcase film
Built by @alisaqqt — follow for more agent-skill experiments.
Inspired by the collage-ad workflows of Stav Zilber, rom1trs and Higgsfield, and by Vox's explainer visual language.
Built end to end on Atlas Cloud — one prompt, one film.
MIT © 2026 Alisa Qian