Skip to main content
Video Lab helps Codex, Claude Code and similar agents produce narrated videos on your computer. It is audio-first: the narration is generated before the picture, and its word timestamps become the clock. Visuals are anchored to words, cue markers and pauses instead of hard-coded seconds, so the picture changes exactly when the voice says so. Video duration comes from the narration; there is no fixed minimum or maximum. The agent works in this order: script with cue markers → Breeze TTS narration with word timestamps → beat sheet → timeline of visuals → preview and review → MP4. By default an agent asked for a complete video continues through all stages; you can ask it to stop at a script draft, a voice audition, the finished narration or the visual review.

Requirements

  • Node.js, FFmpeg/ffprobe and Playwright Chromium on the computer that renders. breeze video doctor checks them without a login and reports anything missing.
  • A Breeze account with at least 400 credits for audio, preview, render, preflight and batch. Only newly generated narration consumes credits (see Costs).
  • Voices on breeze-tts-2 or breeze-tts-2-multilingual. Only these models return the word timestamps Video Lab uses.

Create a video

Edit script.json: write the narration, bind every speaker role to a saved voice (breeze voice list, breeze voice get) and mark visual beats with {#cue} markers. Then generate the narration:
Read output/audio/beats.md, decide one visual event per cue, and author timeline.json with its motion modules, images or HTML scenes. Then compose, check and review:
Review output/preview/contact-sheet.png and output/preview/sync-report.json, fix the timeline, and repeat. When the frames match the voice, render the final video:
breeze video preflight runs audio, compose, inspect and render in one command. breeze video validate checks that every clip loads, and breeze video snapshot saves representative frames.

Templates

init --template starts from a complete, working project. Each template includes its script, timeline, theme, motion modules and short notes on what to change. Pass --force to apply a template to an existing project directory; only the template’s own files are replaced. breeze video capture-url --url <url> --project <dir> saves screenshot.png (1280×720 viewport, or --full-page, or --selector <css> for one element), page.html and capture.json under assets/captures/<run-id>/. Element rects in capture.json are page CSS pixels; its screenshot object records the PNG’s pixel width and height, device_scale_factor, origin and, for --selector, selector_rect. A rect in screenshot pixels is (rect.x − origin.x) × device_scale_factor, likewise for y.

Project files

Manifest

Presets are landscape-1080p (1920×1080), landscape-720p (1280×720), portrait-1080p (1080×1920) and square-1080p (1080×1080), all at 30 fps. Explicit width, height (even, 320–3840 and 240–3840) and fps (1–60) override the preset. safe_area sets {top, right, bottom, left} margins in pixels. The defaults are 5% on each side for landscape and square, and extra room at the bottom and right for portrait so text clears platform controls. theme names a project CSS file; theme.css is used automatically when present.

Script

  • {#id} marks the exact word where the picture should change. Markers are removed before speech generation, so adding or moving them never regenerates narration. Cue ids are unique across the script.
  • pause_after_seconds is the audible silence between this segment’s last word and the next segment’s first word (default 0.6 seconds, 0 after the last segment). Pauses are the natural places for cuts.
  • Stable speaker direction belongs in voices.<role>.instructions; per-segment instructions add emphasis, pace and emotional changes. guidance_scale defaults to 1 (range 1–10); audition 1–2 for continuous narration.
  • A segment can override language. Inline audio tags such as [叹气] or (pause) are sent to TTS and removed from captions.
Video Lab never trims speech or changes its speed to fit a shot.

Narration outputs

breeze video audio generates each segment with word timestamps, resumes interrupted jobs and reuses cached takes. If a cached take’s timestamp file is missing or was edited, it downloads the timestamps again for free; if that download fails, the take keeps estimated word timing with a warning instead of being regenerated. It writes to output/audio/:
  • narration.wav — the complete narration with lead-in, pauses and tail.
  • audio.json — segments with speech start and end times, every word with its time, phrases, cue times, measured pauses and advisory warnings (for example an unusual speech rate or estimated timing).
  • beats.md — a readable score of the narration that agents use as their “ears”:
Each line is a phrase at its spoken start, with cue markers in place, *word* for stressed words and ‖ for measured pauses.

Timeline

timeline.json holds tracks of clips. Track 0 is the base and must cover the whole narration without gaps; later tracks are overlays that can keep elements on screen across base cuts, with captions usually on top.
Clip start and end are anchors on the narration: Clip kinds: Clips can enter with a cut, fade, wipe-left, wipe-right, wipe-up or zoom transition; overlay clips can also exit with one. Motion modules and HTML scenes must produce the same frame for the same time: no randomness, clocks, timers or network. All fonts, images and libraries live inside the project. The bundled Video Lab Skills include the complete timeline schema, the motion runtime API and recipes. When you request pictures, the agent uses suitable supplied images and otherwise uses the image generation available in its host (Codex uses its built-in tool without an image API key) unless you name another provider. If generation is unavailable, the agent explains the limitation and asks before substituting code-drawn visuals. When the agent can view images, the bundled Skills direct it to review generated images for anatomy, scene logic and continuity before use; inspect is a technical check and does not certify image content.

Review: inspect, preview and contact sheet

inspect checks layout (overflow, clipping, contrast, occlusion, cropped images) and timing (cuts inside a word, clips shorter than 0.6 seconds, estimated anchors) at representative moments. It also seeks every animated clip forward, backward and after a fresh load, and checks that it stays still while nothing seeks; a clip that draws different frames for the same time, or animates from a clock instead of seek time, blocks rendering. --strict fails on warnings. preview renders a fast, low-resolution review video to output/preview/preview.mp4 with narration and effects, then writes:
  • contact-sheet.png (and further pages for long videos): one labelled frame shortly after every cue, at every base clip’s midpoint and at the last frame, beside the phrase being spoken. Ask of every frame: does it show what the voice is saying right now?
  • sync-report.json: when the picture visibly changes compared with each cue (ok, early, late or none), hard changes inside a word, and long stretches of speech without a visual change. The report is advisory; small or gradual changes may not register.
Preview never generates narration. --width (default 640), --fps (default 12), --workers and --no-sound-effects tune it.

Render outputs

render captures frames with parallel browser pages (--workers, default up to 4), encodes resumable H.264 chunks that are reused when unaffected, and masters the soundtrack to −16 LUFS with a −1.5 dBTP true-peak ceiling. It writes to output/ (or --out-dir): --force replaces an existing final.mp4 while reusing valid caches. --no-audio renders a silent rehearsal from existing narration. --keep-frames keeps captured frames for debugging. Rerun the same command to resume after an interruption.

Sound effects and ambience

Effects are optional; narration alone is a valid result, and cuts do not automatically receive a whoosh. An optional sound-design.json (version: "video-lab.sound-design.v1", mode: "auto") lists cues with a unique id, kind (effect or ambience), a project-local audio asset, start/end anchors (the same anchors as the timeline, for example "@beats"), purpose and source, plus optional gain, fades, source offset and looping. Narration ducking is on by default. The CLI mixes local files; it does not generate sounds. If you ask for no sound effects, the agent sets mode to off and renders with --no-sound-effects, which keeps narration and also works on preview, preflight and batch. --no-audio removes all audio.

Costs

Only new narration generation consumes credits: the first audio run, changed text or voice settings, and --regenerate. Reusing cached takes, changing pauses or cue markers, re-downloading timestamps, compose, inspect, preview and render do not consume credits. Rendering never calls TTS implicitly.

Batch

breeze video batch --manifest batch.json --dry-run validates every project without generating or rendering. An actual run executes preflight per job, checks your account for each job and stops at the first failure while keeping caches. Jobs accept no_audio: true and no_sound_effects: true. Video Lab runs locally. It does not render in the cloud, generate music or sound effects, or publish your video.