Vibe Scene

Vibe Scene

VibeFrame scene projects are editable video projects built from:

• STORYBOARD.md - beats, narration, backdrop cues, duration hints
• DESIGN.md - visual identity, palette, typography, motion rules
• compositions/scene-*.html - per-beat HTML compositions
• index.html - root timeline that references scene compositions
• assets/ and renders/ - generated inputs and final outputs

Use this skill when the user wants editable HTML-based scene composition, storyboard-to-MP4 work, or a host-agent authoring loop.

Use the top-level commands for the main project lifecycle:

vibe init my-video --profile agent --ratio 16:9
vibe build my-video
vibe render my-video -o renders/final.mp4

The vibe scene ... namespace is the lower-level authoring surface: install-skill, compose-prompts, list-styles, add, and lint.

Pick The Right Path

Default recommendation for public demos and reproducible dogfood runs:

vibe init my-video --profile agent --ratio 16:9
# edit DESIGN.md and STORYBOARD.md
vibe build my-video \
  --tts kokoro \
  --skip-backdrop \
  --skip-render
# (the host agent authors compositions/scene-*.html, then re-run vibe build)
vibe scene lint index.html --project my-video --fix
vibe render my-video -o renders/final.mp4 --quality standard

Use --skip-backdrop when you want a low-cost composition test. Remove it when the demo should exercise OpenAI image generation from each beat's backdrop cue.

Host-Agent Loop

Use this when Claude Code or another coding agent should be the reasoner that authors compositions/scene-*.html.

vibe build my-video \
  --tts kokoro \
  --skip-backdrop \
  --skip-render

vibe scene compose-prompts my-video --json

If vibe build returns a needs-author plan:

1. Read the compose plan.
2. Author each missing compositions/scene-<id>.html.
3. Run vibe scene lint index.html --project my-video --fix.
4. Fix remaining lint errors by editing the HTML.
5. Run vibe render my-video.

Hard rules for authored scene HTML:

• Every timed element needs data-start, data-duration, and data-track-index.
• Timed elements must have class="clip".
• GSAP timelines must be paused and registered on window.__timelines.
• Do not use Date.now(), Math.random(), or network fetches in render paths.
• Route final audio through root-level <audio> elements when possible.
• For factual, typography-heavy videos, keep claims and layout in HTML/CSS/JS; treat provider assets as inputs rather than the whole product.

Low-Level Scene Commands

vibe scene install-skill my-video --host auto
vibe scene compose-prompts my-video --json
vibe scene list-styles
vibe scene add intro --project my-video --style announcement --headline "Hello"
vibe scene add badge --project my-video --style simple --lottie assets/logo.lottie --lottie-position bottom-left
vibe scene lint index.html --project my-video --json --fix

Run vibe schema scene.<subcommand> before using less common flags.

Overlay a Lottie animation (.json/.lottie) on a scene with --lottie <path>, tuned by --lottie-position (full|center|top-left|top-right|bottom-left|bottom-right), --lottie-scale, --lottie-opacity, and --lottie-no-loop. It renders as a <dotlottie-wc> overlay (no provider call — free).

Narration Word-Sync

During vibe build, generated narration is transcribed at the word level (Whisper) to assets/transcript-<beat>.json whenever narration exists and an OpenAI key is configured. Those word timings are passed into each beat's compose prompt so captions / kinetic typography can be synced to speech.

• On by default; pass --skip-transcript to opt out (no transcription cost).
• No OpenAI key → silently skipped; narration still plays, just without word-level animation timing.
• Timings are advisory and visual-only — the composer never adds audio/SFX from them. For long narration the prompt downgrades to coarse phrase-level anchors.