feat(build): word-level transcript → per-beat compose prompt (#204)

[kiyeonjeon21]

Closes the vibe build half of #204 — word-synced caption / kinetic-type animations.

What

The LLM composer now receives Whisper word-level narration timings so it can sync word reveals to speech. The deterministic vibe scene add emit path already did this; vibe build did not.

How

• New _shared/transcribe-narration.ts — transcribeNarrationWords() (provider-agnostic Whisper word-level transcription of generated narration), readBeatTranscript(), beatTranscriptRelPath(). The inline transcribe block in vibe scene add is refactored to reuse it (single source of truth).
• Asset stage dispatchTranscript() — after narration, transcribe to assets/transcript-<beat>.json when narration exists and an OpenAI key is configured. Cached (skipped when the file exists and narration wasn't freshly regenerated); best-effort (no key / no words → skip, never fails the build). Opt out with --skip-transcript.
• Prompt injection (formatTranscriptSection) — compact, deterministic timing section with a token-budget guard: word-level [start, "word"] table at/below 120 words; phrase-level approximate anchors above. Folded into the user prompt → the compose cache key invalidates when timings change. Carries the existing visual-sync-only guard (no <audio>/SFX).
• Host-agent path (compose-prompts) — exposes transcriptPath and feeds the same timings into its prompt.

Behavior

• Default on when narration + OpenAI key exist; --skip-transcript opts out. No key → graceful skip (narration still plays, no word-sync). Transcription is low/negligible cost (~$0.002/beat).

Tests

• formatTranscriptSection: no / short / oversized transcript + clamping/rounding.
• buildUserPrompt: section omitted without transcript, word-level with, cache-key changes when transcript changes.
• asset stage: writes transcript-<beat>.json when words exist; --skip-transcript writes nothing.
• readBeatTranscript / path helper / non-fatal failure path.
• vibe build --describe schema snapshot updated for --skip-transcript.

Notes / follow-ups

• Dry-run does not itemise the (~$0.002/beat) transcription cost as a separate line — intentional, below plan rounding noise.
• LLM prompt-tuning for how aggressively it uses the timings is a separate quality pass.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vibeframe	Ready	Preview, Comment	Jun 22, 2026 11:08am