@openvidstudio/mcp-server 0.1.0

package/docs/HIGGSFIELD.md

@@ -0,0 +1,118 @@
+# HIGGSFIELD.md: the AI b-roll tier
+
+This is the protocol for the one gap real capture can't fill: an
+atmosphere/b-roll shot with no real product UI in it at all (a desk/hands
+shot, an establishing texture, an abstract visual metaphor). Everything else
+in this pipeline stays real by provenance, per `STYLE.md`; this tier exists
+for the beats where "real" was never an option in the first place.
+
+## Prerequisite
+
+Using this tier at all requires two things the calling dev, not
+openvidstudio, provides:
+
+1. **A Higgsfield subscription.**
+2. **The Higgsfield MCP connector enabled in the dev's AI coding agent
+   session** (Claude Code, Cursor, or whatever else the dev is running
+   openvidstudio's own MCP tools alongside).
+
+openvidstudio never holds a Higgsfield API key, never authenticates to
+Higgsfield, and never bills anyone for a generation. There is no clean way
+for one local MCP server to reach into a different, already-authorized MCP
+connection that only the calling agent's own client session holds: MCP's
+protocol gives a server exactly three ways to ask its client for help
+(sampling, for an LLM completion; elicitation, for a form/URL prompt to the
+user; and a roots list), and none of them is "call this other tool on this
+other server for me." So the design here isn't a workaround, it's the only
+architecture the protocol actually supports: the calling agent uses its own
+Higgsfield connection directly, and openvidstudio only receives what that
+connection already produced.
+
+## Config gate
+
+`import_higgsfield_clip` (the one tool this tier adds) only appears in this
+server's tool list when a project's `openvidstudio.config.json` has
+`"hasHiggsfield": true`. If that field is `false`, or missing entirely
+(the default for any project that hasn't set it), the tool is not
+registered at all, not present-but-erroring: it simply won't show up in the
+calling agent's tool list for that project.
+
+`init_project` is what sets this field, from the dev's own answer to
+`PLANNING.md`'s intake question 4 ("Higgsfield access: yes or no"). A
+project that answered "no" (or never ran that question) genuinely does not
+have this tool available, and any beat that would have needed it either
+gets dropped or reworked as a `dom-demo`, per `PLANNING.md`'s decision tree.
+
+## Scope: b-roll and atmosphere only, never product UI or on-screen text
+
+This is `STYLE.md`'s provenance rule, restated as the operational
+consequence for anyone writing a Higgsfield prompt: an AI-generated clip
+must never carry on-screen product text or real UI. Real product surfaces
+are ground truth by provenance (DOM-rendered, screenshotted, or
+screen-recorded, all captured per `CAPTURE.md`); an AI-generated clip is not
+ground truth of anything, and mixing the two undermines the entire premise
+of this pipeline, that everything on screen came from the real product.
+
+Be honest about what enforces this: nothing here does, at the code level.
+Neither the calling agent's own Higgsfield generation call nor
+`import_higgsfield_clip`'s ingest step inspects the resulting video's
+content. This is a convention enforced by doc guidance and by whoever
+reviews the video before it ships, not a filter that can catch a
+prompt-writer who ignores it. A "Higgsfield-text soft-guard linter" (an
+automated check that flags a generated clip likely to contain readable text
+or UI-like chrome) is a plausible future nice-to-have, but it is explicitly
+out of this tool's v1 scope and does not exist yet.
+
+## Prompt-writing guidance
+
+Write a Higgsfield prompt around the shot's actual visual purpose in the
+scene, the same way you'd brief a stock-footage search, not around "the
+product." A prompt like:
+
+> a hand typing on a mechanical keyboard, warm desk lighting, shallow depth
+> of field
+
+describes the atmosphere the beat needs and gives the model nothing to
+hallucinate a screen or interface out of. A prompt like "show the product"
+or "someone using the app" invites the model to render its own guess at UI,
+text, or branding, which is exactly what this tier must never produce.
+Before writing the prompt, know which specific beat the clip is standing in
+for and what mood or texture it needs to carry; write to that, not to the
+feature the beat happens to sit next to.
+
+## What `import_higgsfield_clip` actually does
+
+`import_higgsfield_clip` is deliberately not a wrapper with opinions about
+video generation. It does not call Higgsfield's `generate_video` or
+`jobs_wait` tools itself, and it does not talk to Higgsfield at all. The
+calling agent does that part, over its own already-authorized Higgsfield
+MCP connection, exactly the way it would for any other Higgsfield request in
+the same session. Once that generation finishes, the agent has a result:
+either a downloadable URL or a local file path. `import_higgsfield_clip`'s
+entire job is taking that result and landing it at this project's asset
+convention.
+
+Input:
+
+```
+{
+  projectRoot?: string,       // defaults to the calling agent's cwd
+  beatId: string,
+  source: { type: "url"; url: string } | { type: "path"; path: string },
+  outPath?: string,           // override; default is public/video/<beatId>.mp4
+}
+```
+
+Behavior: fetches the URL or reads the local file, then writes those bytes
+to `public/video/<beatId>.mp4` under `projectRoot`, the exact same
+convention `capture_screen_recording` and `scaffold_scene`'s
+`higgsfield-clip` kind already use. That convention match is load-bearing:
+a `higgsfield-clip` scene's `<OffthreadVideo src=...>` expects the asset at
+that path regardless of which tool produced it, so a `higgsfield-clip`
+scene is structurally identical to a `real-recording` scene once the asset
+exists.
+
+Returns `{ outPath, beatId }` on success. On failure (a bad or unreachable
+URL, a missing local file, a failed download), it returns a structured
+error the same way every other tool in this package does; it never throws
+uncaught.

package/docs/NARRATION.md

@@ -0,0 +1,111 @@
+# NARRATION.md: voice, music and sound
+
+Narration used to be entirely the caller's problem. It is not any more:
+`generate_narration` reads `beats.json` and writes one clip per beat to the path
+`stitch_composition` already looks in. This doc covers what that tool does, what it
+deliberately refuses to do, and why generated voiceover usually sounds synthetic.
+
+## The short version
+
+```
+generate_narration  ->  public/audio/vo/<beatId>.mp3
+stitch_composition  ->  picks them up automatically
+```
+
+## Why generated voiceover sounds like a robot
+
+Rarely the engine. Almost always the stretching.
+
+Every engine reads at its own pace, so a clip rarely lands exactly on its beat. The
+obvious fix is to time-stretch it to fit. A pitch-preserving stretch past roughly ten
+percent is audible, and past twenty it is the drawly, processed sound people mean by
+"AI voice". Building the openvidstudio demo, one beat was stretched to **0.645**, a
+35 percent slowdown, and that single clip was most of why the whole video sounded
+synthetic.
+
+So `generate_narration` clamps stretching to **0.9 to 1.12**. When a line still does
+not fit, it says so and names the beat rather than mangling it, because the real fix
+is one of:
+
+- **Too short for the beat.** Add a sentence, or shorten the beat.
+- **Too long for the beat.** Cut words, or lengthen the beat.
+
+Both are edits to `beats.json`, which is yours to change. Stretching audio to hide a
+mismatch trades a timing problem for an audible one.
+
+## Pace
+
+`validate_beats` enforces SCRIPT.md's 2.3 to 2.9 words per second as a hard floor and
+ceiling, per beat. It is a floor as well as a ceiling, so a beat can be rejected for
+being too sparse, which is not the failure most people expect.
+
+`plan_beats` gives you the word budget per beat up front, so narration is written to
+a number instead of guessed and revised.
+
+## Engines
+
+| Engine | Quality | Speed | Runs locally |
+|---|---|---|---|
+| `edge-tts` (default) | good | about a minute for five minutes of speech | no, sends text to Microsoft |
+| `say` (macOS) | fair | instant | yes |
+| `espeak` | poor | instant | yes |
+
+`edge-tts` needs `pip install edge-tts`.
+
+**If the text must not leave the machine**, use `say` on macOS, or wire up a local
+neural model. A local model on CPU is slow: one measured at a real time factor of
+41.9x, meaning six minutes of compute for nine seconds of audio, or about three and
+a half hours for a five minute video. Fine overnight, not fine in a loop.
+
+**If you want it to sound genuinely good**, record it yourself. A real voice beats
+every engine here, and for a launch video it is worth the hour.
+
+## Silence is silent
+
+`stitch_composition` skips a missing `public/audio/vo/<beatId>.mp3` with no error and
+no warning. A half generated narration renders successfully and simply plays silent
+in those beats.
+
+Two things catch it:
+
+- `generate_narration` reports which beats have audio and which do not
+- `validate_scenes` flags every beat with no narration file
+
+Neither is optional if you care whether the video has a voice.
+
+## Music and sound effects
+
+Everything ships synthesized, generated by `scripts/gen-sfx.sh` with ffmpeg. Nothing
+is sampled or licensed, so **a rendered video carries no third-party audio rights**.
+No attribution, no content ID, no licensing questions.
+
+| File | Sound |
+|---|---|
+| `key_a/b/c.wav` | Mechanical key thocks, three variants so typing is not a metronome |
+| `key_enter.wav` | Deeper thock for the end of a command |
+| `click.wav` | Cursor click |
+| `whoosh.wav` | Camera move or cut |
+| `blip.wav` | UI reveal |
+| `success.wav` | Rising two tone |
+| `bell.wav` | Struck harmonic stack, long decay |
+| `music-bed.mp3` | 60s ambient pad, loops |
+
+Regenerate any of them by editing `scripts/gen-sfx.sh` and running it. The
+`sfx.tsx` API does not change, so you can swap in a recorded pack later without
+touching a scene.
+
+### Using the music bed
+
+```tsx
+import { MusicBed } from "@openvidstudio/core";
+
+<MusicBed durationInFrames={9000} volume={0.16} />
+```
+
+Keep it quiet. It sits under narration, and 0.16 is already at the edge of noticeable
+when a voice is speaking over it.
+
+### If you want real music instead
+
+Pixabay Music and the YouTube Audio Library are both no-attribution. Drop the file at
+`public/audio/music-bed.mp3` and `stitch_composition` picks it up, same as narration.

package/docs/OVERVIEW.md

@@ -0,0 +1,112 @@
+# OVERVIEW.md: what openvidstudio is
+
+openvidstudio is a free, open-source video-generation add-on for any
+software project. It's built on Remotion (React-based programmatic video)
+and Playwright (real-browser automation), and it's driven entirely through
+MCP tools by whatever AI coding agent you're already using (Claude Code,
+Cursor, ChatGPT, or anything else that speaks MCP). There's no separate app
+to open, no timeline editor, no manual keyframing.
+
+## The core idea
+
+Launch and demo videos for software usually mean one of two compromises:
+record a screen and cut it in a traditional editor (slow, and it looks like
+a screen recording), or hand a brief to an AI video generator (fast, but
+the UI, the product's actual text, and every detail a viewer would
+recognize get hallucinated away).
+
+openvidstudio does neither. It builds a cinematic camera, push-ins, drift,
+shallow depth of field, an oversized cursor acting as an on-screen actor,
+that moves over your product's real, DOM-rendered UI, composited from real
+Playwright-captured screenshots and (v1 scope) full-viewport screen
+recordings of the actual running app. Nothing on screen is invented: every
+piece of product text a viewer can read came from the real product.
+
+Where the real UI genuinely can't produce a shot (an atmosphere beat, a
+desk/hands shot, some establishing texture that isn't product UI at all),
+openvidstudio has an optional Higgsfield AI b-roll tier for exactly that
+gap, and only that gap: an AI-generated clip never carries on-screen
+product text or real UI, full stop. See `HIGGSFIELD.md` for that tier's
+protocol: the calling agent generates the clip itself over its own
+Higgsfield MCP connection, and openvidstudio's `import_higgsfield_clip`
+tool only ingests the result into this pipeline's asset convention.
+
+## Why not a hosted AI-storyboard tool?
+
+There are hosted, MCP-callable pipelines that go storyboard to AI-generated
+visuals plus VO plus music plus captions in one pass (Motion.so is one real
+example). Those are genuinely fast for a rough pacing/storyboard draft to
+react to, and openvidstudio doesn't try to replace that use case.
+
+But that whole model, AI-generated visuals standing in for the product,
+is the opposite of why openvidstudio exists: no traditional editor, no
+AI-generated footage of the product itself, pixel-perfect real UI on
+screen. openvidstudio deliberately doesn't work that way. A tool like that
+isn't a component of this pipeline and isn't the model to reach for when
+the goal is a video that shows what a real product actually looks like.
+
+## The intended flow
+
+1. **Intake.** The calling agent asks the guided question set in
+   `PLANNING.md` (or, if the dev pastes a README, feature list, or other
+   existing material instead, folds that into the same beat candidates;
+   see `PLANNING.md`'s free-form-input section).
+2. **Draft.** The agent turns intake answers into a `beats.json` draft:
+   timing, VO, and, critically, a decided `captureMethod` for every beat,
+   per `PLANNING.md`'s decision tree.
+3. **Approval gate.** The agent shows the dev the full drafted
+   `beats.json`, not a summary, and gets explicit approval before writing
+   anything to disk. This is a protocol rule for the calling agent, not
+   something enforced by the tooling itself; see `PLANNING.md`.
+4. **Execute.** Once approved, the agent runs capture (screenshots and/or
+   recordings, per `CAPTURE.md`'s protocol) and stitches the composition,
+   following `PIPELINE.md`'s beat-to-scene-to-composition-to-QC loop and
+   `STYLE.md`'s binding art-direction rules throughout.
+
+## Doc map
+
+| Doc | What it covers |
+|---|---|
+| `PIPELINE.md` | Step-by-step: beats.json, scenes, composition, QC loop, render |
+| `STYLE.md` | Binding art-direction rules: camera, depth of field, lighting, cursor, motion, palette, type |
+| `CAPTURE.md` | The real-capture protocol for screenshots and screen recordings: the Playwright zoom-desync bug and its fix |
+| `PLANNING.md` | The guided intake to beats.json protocol, including the capture-method decision tree |
+| `SCRIPT.md` | VO pacing, duration math, and the claim-obligates-visual writing rule |
+| `HIGGSFIELD.md` | AI b-roll tier protocol: prerequisites, the `hasHiggsfield` config gate, provenance scope, prompt-writing guidance, and how `import_higgsfield_clip` ingests a clip the calling agent already generated |
+
+## Two rules that changed on the way to being a public tool
+
+This pipeline started as a private tool built for one person's own repos.
+Two of its rules only made sense in that narrower context and don't hold up
+once other people's projects are the ones going through it. Both are
+documented changes here, not silent drops:
+
+- **"No GitHub-star click action in a CTA."** The private version of this
+  pipeline treated this as a hard QC-fail rule: it assumed every video was
+  for a personal, no-self-promo repo. Here it's the default `RepoCta`
+  behavior (no star action baked in, unless a project opts in), not
+  something QC fails on. This pipeline now serves other people's projects,
+  and a hardcoded no-self-promo stance doesn't make sense for every user
+  the way it did for a single person's own repos.
+- **Terminal windows with a fixed title and slash-command convention.** The
+  private version hardcoded a specific title and command prefix. Here it's
+  a documented default convention a project can override, not a QC-fail
+  rule, for the same reason: other people's terminals show other people's
+  commands.
+
+## One refinement: the "DOM text" rule is now stated by provenance, not medium
+
+The private version's rule was "all text is DOM text," reasoned from
+medium: if it wasn't rendered as DOM inside Remotion, it wasn't trusted.
+That was too strict. A genuine screen recording of the real, running
+product isn't AI-hallucinated; it's ground truth, exactly like a screenshot
+is. A medium-based rule would have wrongly forbidden a legitimate capture
+method just because it wasn't literally re-rendered as DOM text inside the
+composition.
+
+The restated rule (full detail in `STYLE.md`): real product UI/text,
+whether DOM-rendered, screenshotted, or screen-recorded, is always allowed
+on screen, because it's ground truth by provenance. AI-generated clips
+(Higgsfield or any future model) never carry on-screen product text or real
+UI; they stay b-roll/atmosphere only. This is a refinement over the private
+original, not a silent rewrite.

package/docs/PIPELINE.md

@@ -0,0 +1,173 @@
+# PIPELINE.md: how a new video gets made
+
+Brief in, video out. Follow in order; `STYLE.md`'s rules are binding at
+every step. Beat authoring itself is driven by `PLANNING.md`'s guided
+intake process: read that first, before hand-writing a `beats.json`.
+
+## 0. Prereqs (once per machine)
+- Install dependencies for the scaffolded project (`@openvidstudio/core`
+  plus Remotion/React, see the project's own `package.json`).
+- An SFX pack exists at `public/sfx/` (regen: `bash scripts/gen-sfx.sh`,
+  needs ffmpeg).
+
+## 1. Beats file (the single source of truth)
+Create `<video>/beats.json`:
+- `fps`, `title`, `beats[]`: each beat has `id`, `start` (frame),
+  `duration` (frames), `visual`, `vo`.
+- Beats must be contiguous (`start` = previous `start + duration`). 30 fps.
+- This file drives: scene sequencing, the markers/SRT export, and the VO
+  script table.
+- **`captureMethod`**: every beat's `visual` block now carries one of
+  `"screenshot"` | `"recording"` | `"dom-demo"` | `"higgsfield"`, decided
+  per `PLANNING.md`'s decision tree during intake. At a glance:
+  `screenshot` is a real captured still of the running product;
+  `recording` is a real captured full-viewport screen recording of the
+  running product; `dom-demo` is a hand-authored scene built from the
+  project's real design tokens/copy, for a claim the real product can't
+  currently back with a capture; `higgsfield` is an AI-generated b-roll
+  clip for a shot that isn't product UI at all. `PLANNING.md` owns the
+  full field spec and decision tree; this file just needs every beat to
+  carry the field.
+- Two beat arcs, pick by product complexity:
+  - **Simple demo** (single core feature): hook (8s), problem (11s), demo
+    x2-3 (12-14s each), differentiator (10s), cta (9s). 60-75s total.
+  - **Packed-hook, multi-feature**: one dense ~15s hero beat whose VO
+    states every core thing the product does in one pass (what it is,
+    what a user can do, how it's verified/differentiated) before any demo
+    beat, written so a judge or cold viewer understands the whole pitch
+    from audio alone in the first 15s, even muted-video-unaware. Then one
+    demo beat per feature claimed in the hook (so nothing gets asserted in
+    VO without being shown), differentiator recap, cta. Total scales with
+    feature count but stays under whatever hard ceiling the brief sets:
+    budget ~10-20s/demo beat and check the running total as you add
+    beats, don't let it creep past the brief's stated limit "for
+    completeness."
+- No em dashes in any on-screen string or VO line (writing rule).
+- **Claiming a feature in VO obligates showing it.** If a beat's VO
+  asserts something the product does, either show the real thing or say
+  so isn't wired yet and build a labeled `dom-demo` instead (see
+  "Constructed mockups" below): never let VO overclaim past what the
+  visual backs up. Full generalized version of this rule: `SCRIPT.md`.
+
+## 2. Scenes
+One file per beat. Rules:
+- Any beat with `captureMethod: "screenshot"` or `"recording"`: capture it
+  per **CAPTURE.md**, not ad hoc. That doc exists because uncorrected
+  captures reliably come out small, soft, or bleed in content from a
+  neighboring page section, both tracing to the same root cause (an
+  uncompensated Chrome zoom desync in the Playwright profile).
+- **Screen recordings** (`captureMethod: "recording"`): composite as an
+  `OffthreadVideo` inside a `Layer`, the same camera-keyframe pattern as a
+  static `<Img>`. The camera moves over the recording exactly like it
+  would over a still. v1 scope is fixed full-viewport recordings only: no
+  post-hoc DOM-rect cropping of a moving recording (that's future work; a
+  moving recording can't be re-cropped to a DOM rect the way a still
+  screenshot can, because the rect would need to track the content frame
+  by frame).
+- **Constructed mockups** (`captureMethod: "dom-demo"`), for a claim the
+  product doesn't do yet, or where a real screenshot isn't available or
+  would show something contradicting the claim: build it as a hand-coded
+  panel using the project's real design tokens and colors, reusing real
+  copy, real claim IDs, or real UI conventions from an actual screenshot
+  elsewhere in the same video where possible, so it reads as a
+  continuation, not an invention. For example: a fictional product's
+  "export your data" beat, before that feature is wired up, might reuse
+  the exact card style the viewer already saw in a real, captured
+  screenshot two beats earlier: same panel, same accent color, same copy
+  voice. Never screenshot a real page whose own on-screen copy contradicts
+  the claim you're making about it. A real settings page stating "your
+  data stays private, never shared" directly contradicts a beat's VO
+  claiming a public-sharing feature; screenshotting it for that beat would
+  put the opposite of the VO on screen. Where a real adjacent page
+  genuinely backs part of the claim, use the real screenshot for that part
+  and confine the constructed part to just the aspirational connection: a
+  real screenshot of a real results page, bridged by one constructed
+  arrow to a hand-built "share" panel, since the results page is real but
+  the sharing wiring isn't.
+- Every scene = `CinematicScene` with camera keyframes. Motion never stops
+  (min: subtle push-in).
+- Captions, title cards, dips/fades: always in the `overlay` prop
+  (screen-space). Never inside the rig.
+- Reuse the library first: `TerminalReplay`, `CodePanel`, `ChecklistPanel`,
+  `BrowserFrame`, `KineticText` (`TitleSlam`/`Caption`), `CursorActor`,
+  `RepoCta`. Build a new component only when a beat truly needs it, then
+  keep it generic.
+- Terminal windows: pick a title and slash-command convention and stay
+  consistent within a video (see `OVERVIEW.md` for why this is now a
+  documented default, not a hard rule).
+- CTAs: `RepoCta`, no star action by default (see `OVERVIEW.md`).
+- Camera keyframes derive from the terminal timeline
+  (`computeTerminalTimeline`) where applicable, so cuts land frame-exact on
+  content events.
+- SFX: typing via `TerminalReplay` (built in), `Whoosh` on cuts/whips,
+  `Blip` on reveals, `SuccessChime` on completion moments. Real
+  third-party components the product actually uses (an embeddable widget,
+  a real chart library, etc.): npm install and render them, never fake a
+  screenshot.
+
+## 3. Composition
+`<video>/<Name>Demo.tsx`: `<Series>` mapping `beats.json` ids to scene
+components. Register in the project's `Root.tsx` with duration from beats.
+
+## 4. Preview + QC loop
+- `npm run dev` for live preview while writing scenes.
+- Render, then extract frames at each beat midpoint:
+  `ffmpeg -nostdin -ss <t> -i out/<video>.mp4 -frames:v 1 -q:v 3 out/qc/<t>.jpg -y`
+- QC checklist (all must pass):
+  - [ ] Text crisp on a 1080p pause-frame at every zoom level
+  - [ ] Zero linear easing; every scene has camera motion
+  - [ ] Captions fully visible (screen-space) at all camera positions
+  - [ ] No em dashes on screen
+  - [ ] SFX lands on the visual events (spot-check typing + whip cuts)
+  - [ ] Beat durations match beats.json
+  - [ ] Glassmorphism on captions/cards; UI content detailed, not skeleton
+  - [ ] Every real-screenshot or real-recording beat: camera `scale` in
+        120-250% (STYLE.md), frame centered on the stage
+        (`LEFT + FRAME_W/2 == 960`), no leftover dead space around a
+        small, unzoomed shot
+  - [ ] Pull a frame from the END of every real-screenshot/recording beat
+        specifically, not just the midpoint: a static crop that looks fine
+        early can push the important content (the actual payoff, not just
+        the headline) off the bottom of frame once the camera has zoomed
+        in
+  - [ ] Every claim the VO makes has a matching visual in the same or an
+        adjacent beat; if a beat is a `dom-demo`, confirm it isn't a
+        screenshot of a real page whose own on-screen text contradicts the
+        claim
+
+## 5. Render + exports
+- `npx remotion render <composition-id> out/<video>.mp4`
+- `node scripts/markers.mjs <video>` writes `out/<video>-markers.json` and
+  `out/<video>-vo.srt`
+- Write `<video>/script.md`: VO table (timestamps from markers), delivery
+  notes, description draft. See `SCRIPT.md` for VO pacing/duration rules.
+
+## Asset conventions
+
+Every tool in this pipeline that reads or writes a beat's media agrees on
+these paths (relative to the scaffolded project root). Get an asset onto
+disk at the wrong path and the tool that's supposed to consume it either
+errors (scenes reference a `staticFile` that 404s at render time) or, for
+VO specifically, silently omits the layer with no warning:
+
+| Asset | Path | Written by | Read by |
+|---|---|---|---|
+| Screenshot | `public/images/<beatId>.png` | `capture_screenshot` | the `real-screenshot` scene `scaffold_scene` generates |
+| Recording / Higgsfield clip | `public/video/<beatId>.mp4` | `capture_screen_recording` / `import_higgsfield_clip` | the `real-recording` / `higgsfield-clip` scene `scaffold_scene` generates |
+| VO narration | `public/audio/vo/<beatId>.mp3` | (dev-provided, e.g. an edge-tts run) | `stitch_composition`, only if the file exists at this exact path when it runs |
+| Music bed | `public/audio/music-bed.mp3` | (dev-provided) | `stitch_composition`, only if the file exists at this exact path when it runs |
+
+**VO omission is silent.** `stitch_composition` checks
+`public/audio/vo/<beatId>.mp3` for every beat and just skips the Audio
+layer for any beat where the file isn't there, no error, no warning. A
+video with a beat missing its VO file renders fine and plays with no
+narration for that beat; the QC checklist below is the actual backstop,
+not a tool error.
+
+## Known flakes
+- Webpack "wasm-hash / Cannot read properties of undefined" on render:
+  `rm -rf node_modules/.cache` and retry.
+- `npx remotion skills add` fails on Windows (spawn EINVAL): use
+  `npx -y skills@1.2.0 add remotion-dev/skills` directly.
+- Run npm commands from the project's own directory (shell cwd resets
+  between calls in some agent harnesses).