Vox Explainer

Vox-Style Explainer Video Pipeline

Produce a complete, narrated, subtitled, scored explainer video from a single topic. The pipeline runs in six stages, each producing artifacts the next stage consumes. Voiceover is generated BEFORE animation because VO duration drives all timing decisions.

TOPIC → 1.Script → 2.Voiceover → 3.Keyframes → 4.Animation → 5.Music → 6.Assembly
         (Claude)   (xAI TTS)    (Seedream)    (Omni Flash)  (MiniMax)  (ffmpeg)

Prerequisites

• ATLASCLOUD_API_KEY environment variable set (get one at atlascloud.ai — free credits on signup)
• ffmpeg and ffprobe installed (with libass for subtitle burning)
• Python 3.10+ with requests
• ~$3–8 in API credit per 60-second film (see cost table in references/atlas-cloud-api.md)

Before making any API calls, verify current endpoint paths and model IDs against https://www.atlascloud.ai/docs — media model APIs evolve quickly. The patterns in references/atlas-cloud-api.md were verified July 2026.

Project structure

Create this layout for every film and keep it — every stage reads from and writes to it:

project/
├── brief.md            # topic, angle, target length, audience
├── script.json         # beats with narration, shot descriptions, captions
├── audio/
│   ├── vo/             # beat_01.mp3 ... beat_NN.mp3
│   ├── vo_durations.json
│   └── music.mp3
├── frames/             # keyframe_01.png ... style_anchor.png
├── clips/              # clip_01.mp4 ... (silent animated clips)
├── subs/               # captions.ass
└── final/              # film.mp4

Stage 1 — Script

You write this yourself. No API call. This is the stage that most determines quality — a great script with average visuals beats the reverse.

Read references/vox-style-guide.md (Writing section) before drafting. Core rules:

1. Structure as beats. A beat = one narration paragraph (1–3 sentences, 8–14 seconds spoken) + one visual. A 60-second film is 6–8 beats; 3 minutes is 16–22 beats.
2. Vox narrative arc: cold-open hook (a surprising concrete fact or question) → context ("to understand X, you have to go back to...") → escalating explanation with one clear throughline → complication or twist → resolution that reframes the hook.
3. Voice: second person welcome ("you've probably seen..."), present tense for historical narrative, concrete numbers over abstractions, short declarative sentences. No throat-clearing, no "in this video we will."
4. One idea per beat. If a sentence introduces a second concept, split the beat.

Write script.json:

{
  "title": "Tang Golden Age",
  "topic": "How Tang Dynasty China built the world's largest city",
  "style_seed": "mixed-media paper collage, ink-wash Chinese mountains, vermillion red and aged cream palette",
  "accent_color": "#C0392B",
  "beats": [
    {
      "id": 1,
      "narration": "In the seventh century, Tang China built Chang'an — the largest, richest city on Earth. The whole world came to its gates.",
      "visual": "Emperor Taizong enthroned at center as paper cutout, court figures flanking, pagodas and ink-wash mountains behind, red seal stamp upper right reading 盛唐",
      "caption_text": null,
      "motion": "slow push-in on emperor, clouds drift left, subtle parallax between cutout layers"
    }
  ]
}

caption_text is for on-screen kinetic typography moments (a key stat or term) — most beats leave it null; narration subtitles are handled at assembly. motion becomes the animation prompt in Stage 4.

Stage 2 — Voiceover (xAI TTS v1)

Generate one audio file per beat, then measure durations. These durations are the master clock for the whole film.

Call the Atlas Cloud audio endpoint per beat (model: xAI TTS v1 — see references/atlas-cloud-api.md for the exact request shape and voice selection guidance). Pick ONE voice for the whole film. Vox register: measured, warm, slightly wry — avoid "movie trailer" voices.

After generation, probe every file and write audio/vo_durations.json:

ffprobe -v error -show_entries format=duration -of csv=p=0 audio/vo/beat_01.mp3

{"beats": [{"id": 1, "file": "audio/vo/beat_01.mp3", "duration": 9.83}], "total": 61.2}

Sanity-check total length against the brief. If a beat runs long, tighten the narration and regenerate that beat only.

Stage 3 — Keyframes (Seedream 5.0 Pro)

One keyframe per beat, all in a consistent visual style. Consistency is the hard problem; solve it with the style anchor pattern:

1. Generate the anchor. Use bytedance/seedream-v5.0-pro/text-to-image for beat 1 (usually the title/hook frame). Build the prompt from the style block in references/vox-style-guide.md (Visual Grammar section) + the beat's visual + the film's style_seed and accent_color. Request 16:9, 2K.
2. Review the anchor before proceeding. Regenerate until the style is right — every other frame inherits it.
3. Generate remaining frames with the edit model. Use bytedance/seedream-v5.0-pro/edit with the anchor as a reference image (up to 10 refs supported; anchor + optionally the previous frame). Prompt: "Keep the exact art style, palette, paper-collage treatment, and border framing of the reference. New scene: {beat.visual}"

This locks palette, texture, and framing across the film the way a human art director would.

Every prompt should end with the style suffix (see style guide), which encodes the Vox look: paper cutouts with white borders, halftone dots, tape strips, bold flat geometric accents, generous margins, single accent color.

Frames with caption_text set: instruct Seedream to render the text in a bold condensed sans, since Seedream 5.0 Pro's typography rendering is strong. Keep it under 5 words per frame.

Stage 4 — Animation (Gemini Omni Flash)

Animate each keyframe into a clip via image-to-video. Target clip duration = that beat's VO duration + 0.5s of breathing room (round up to the model's supported increments).

Motion prompts for the collage aesthetic should be SUBTLE — this is the most common failure mode. The Vox look is "motion graphics," not "footage." Good motion vocabulary:

• slow push-in / pull-out (2D camera, not 3D dolly)
• parallax drift between cutout layers
• clouds/smoke drifting laterally
• paper elements sliding in from frame edge and settling
• halftone dots or texture shimmering gently
• a single element animating (flag waving, water rippling) while everything else holds

Explicitly forbid in every prompt: "no camera shake, no 3D rotation, no morphing of faces or text, no style drift, elements remain flat paper cutouts."

Poll each generation task to completion and download to clips/clip_NN.mp4. Generations fail or drift sometimes — review each clip; regenerate any where text warps or the style breaks. Budget for ~15% regeneration.