/vibe-scene

name: vibe-scene
description: Author, repair, render, and inspect VibeFrame scene projects built from STORYBOARD.md and DESIGN.md.

<!-- GENERATED by `pnpm agent-sync` from .agents/skills/vibe-scene/SKILL.md — DO NOT EDIT. -->

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

| Path | Use when | Commands | | -------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | Host-agent authoring | Claude Code/Codex/Cursor writes the scene HTML from a plan (default) | `vibe build`, then `vibe scene compose-prompts` | | Deterministic template | CI or a human demo should produce scene HTML without a coding agent (no LLM call) | `vibe build --composer template` | | Single-scene draft | You need a quick template scene or fallback HTML | `vibe scene add` |

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.

STYLE And STORYBOARD Guidance

Never author scene HTML before `DESIGN.md` exists. Treat it as the hard gate for visual decisions:

• palette and contrast
• typography and hierarchy
• layout density
• animation timing and transition style
• what to avoid

Scenes live in `scenes/`, one markdown file per scene, playing in filename order. Cues go in the frontmatter, direction in the body:

---
type: Scene
narration: "The first sentence the viewer hears."
backdrop: "Specific visual prompt for the scene backdrop"
duration: 5
---

What the scene should show.

`STORYBOARD.md` holds only project frontmatter and direction prose. Beat headings left in it are ignored and reported - move them into `scenes/`, or run `vibe storyboard migrate` on an older single-file project.

Lint Feedback Loop

vibe scene lint index.htm