@openvidstudio/mcp-server 0.1.0

package/docs/PLANNING.md

@@ -0,0 +1,206 @@
+# PLANNING.md: guided intake to beats.json
+
+This is step 0 of building any video with openvidstudio. Read this before
+touching `beats.json`. It defines: the intake question set, how to handle
+free-form pasted material instead, the per-feature capture-method decision
+tree, the full `captureMethod` field spec, and the mandatory approval gate
+before anything gets written to disk.
+
+## 1. Fixed intake question set
+
+Ask the dev, in order, before drafting anything:
+
+1. **Product name and one-liner.** What is it, in one sentence?
+2. **3-6 features to demo.** The specific things the video should show,
+   not a full feature list; pick the ones that carry the pitch.
+3. **Target video length.** Total seconds (or a range); this bounds the
+   beat arc chosen in `PIPELINE.md` (Simple demo vs. Packed-hook,
+   multi-feature).
+4. **Higgsfield access: yes or no.** Determines whether `higgsfield` is an
+   available `captureMethod` for this video at all. If no, every "not
+   product UI" beat either gets dropped or reworked as `dom-demo`.
+5. **Brand info.** Colors, fonts, logo, if the project has its own and
+   wants it over openvidstudio's default palette/type (`STYLE.md`).
+6. **Existing assets to reference.** Screenshots, recordings, a deployed
+   URL, a design file; anything that saves a capture step later.
+
+## 2. Free-form pasted material
+
+If the dev instead pastes a README, a feature list, a Slack thread, or
+similar material, don't force the fixed question set on top of it. Read
+the paste and extract the same six things from it instead:
+
+- Product name/one-liner: usually the README's title plus its first
+  paragraph.
+- Feature candidates: bullet lists, headers, or a "Features" section map
+  directly to feature candidates; pick 3-6 that carry the pitch, same as
+  question 2 above.
+- Target length: often absent from a paste; ask this one directly if it's
+  missing, don't guess it.
+- Higgsfield access: always ask directly; a paste never answers this.
+- Brand info: look for a design-tokens file, a Tailwind config, a
+  `theme.ts`, or explicit brand colors mentioned in the paste; ask only
+  for what's genuinely missing.
+- Existing assets: URLs, screenshot paths, or asset folders mentioned in
+  the paste count directly.
+
+Only ask the dev to fill in whatever the paste didn't already answer. The
+goal is one pass of the fixed question set's information, not necessarily
+one pass of its literal questions.
+
+## 3. Per-feature capture-method decision tree
+
+Run this once per feature/claim the video will make. It's meant to be
+followed mechanically, not judged holistically.
+
+1. Does this claim describe real, working functionality in a running
+   instance of the product right now (not "will do," not roadmap, not
+   something a real screenshot would contradict)?
+   - No: go to step 4 (`dom-demo`).
+   - Yes: go to step 2.
+2. Is the important part of this feature a single held state (one screen,
+   one panel, nothing essential changes while the viewer watches), or does
+   understanding it require seeing something change over time (typing,
+   dragging, a live update, an animation intrinsic to the feature)?
+   - Single held state: `captureMethod: "screenshot"`. Capture per
+     `CAPTURE.md`.
+   - Needs visible change over time: go to step 3.
+3. Can that change be captured by actually interacting with the real,
+   running product on screen, within v1's fixed full-viewport scope (no
+   post-hoc DOM-rect cropping of a moving recording, see `PIPELINE.md`)?
+   - Yes: `captureMethod: "recording"`. Capture per `CAPTURE.md`'s
+     recording section.
+   - No, the motion needed isn't something the product's own UI can
+     produce at all (an atmosphere shot, a desk/hands shot, an abstract
+     visual metaphor with no real UI in it): go to step 4, but check
+     Higgsfield access from intake question 4 first. If access is "no,"
+     this beat either gets dropped or reworked as a still `dom-demo`
+     instead of the motion originally wanted.
+4. `dom-demo`: build a hand-coded panel using the project's real design
+   tokens/copy (question 5's brand info, or `STYLE.md`'s defaults if none
+   was given). Reuse 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. Where a real adjacent
+   screenshot genuinely backs part of the claim, use the real capture for
+   that part and confine the constructed part to just the aspirational
+   connection. Never build a `dom-demo` that contradicts a real,
+   capturable page's own on-screen copy: if a real page says the opposite
+   of the claim, that's a sign the claim needs rewriting, not a signal to
+   avoid screenshotting that page.
+   - If step 3 routed here because Higgsfield access is "yes" and the
+     beat genuinely isn't product UI (atmosphere/b-roll), use
+     `captureMethod: "higgsfield"` instead; see `HIGGSFIELD.md`.
+
+## 4. The captureMethod field spec
+
+Every beat's `visual` block carries a `captureMethod` field:
+
+```
+"captureMethod": "screenshot" | "recording" | "dom-demo" | "higgsfield"
+```
+
+Method-specific fields:
+
+| Method | Extra fields | Notes |
+|---|---|---|
+| `screenshot` | `url`, `interactions` | `interactions` is an ordered array of steps (click/fill/select/hover/scroll/wait, the exact set `capture_screenshot`/`capture_screen_recording` replay) to reach the exact state the beat needs |
+| `recording` | `url`, `interactions` | same shape as `screenshot`; the interactions happen while recording, not before |
+| `dom-demo` | none | the beat's visual is authored directly in its scene file, no capture step |
+| `higgsfield` | `higgsfieldPrompt` | the AI-generation prompt for the b-roll clip; must not request on-screen product text or real UI |
+
+See section 6 below for a concrete `beats.json` fragment with one full,
+working example of each of these four shapes.
+
+## 5. The mandatory approval gate
+
+Once every beat has a decided `captureMethod` and the full `beats.json` is
+drafted: show the dev the full file, not a summary, and get explicit
+approval before persisting it. This applies even to a small, obviously
+fine-looking draft.
+
+The `write_beats_file` MCP tool will refuse to write anything
+`validate_beats` hasn't passed, but that's schema/structural
+validation, not dev approval. The human-approval step itself is a protocol
+rule for the calling agent, not something any tool enforces. Skipping it
+because the tool would technically allow the write is a protocol
+violation.
+
+## 6. Worked example (fictional product, anonymized)
+
+**Product:** "Loomcard," a spaced-repetition flashcard app for technical
+interview prep.
+
+**Intake answers (abbreviated):**
+- One-liner: "Loomcard turns your notes into spaced-repetition flashcards
+  and schedules review so you actually remember them."
+- Features to demo: card review flow, confidence-based scheduling that
+  adjusts in real time, CSV/Anki import (not wired up yet, a roadmap
+  item).
+- Higgsfield access: yes.
+
+**Resulting beats.json fragment** (hook / demo / differentiator / cta, one
+of each `captureMethod` so the shapes above are all represented):
+
+```json
+{
+  "fps": 30,
+  "title": "Loomcard",
+  "beats": [
+    {
+      "id": "hook",
+      "start": 0,
+      "duration": 180,
+      "vo": "Loomcard turns your notes into spaced-repetition flashcards, and schedules review so you actually remember them.",
+      "visual": {
+        "captureMethod": "higgsfield",
+        "higgsfieldPrompt": "slow push-in on a warm desk scene, hands resting near a closed notebook, soft morning light, no screens or readable text in frame, cinematic shallow depth of field"
+      }
+    },
+    {
+      "id": "demo-review",
+      "start": 180,
+      "duration": 120,
+      "vo": "Flip a card, and Loomcard scores your confidence on the spot.",
+      "visual": {
+        "captureMethod": "screenshot",
+        "url": "https://app.loomcard.example/review",
+        "interactions": [
+          { "type": "click", "selector": "[data-testid=flip-card]" },
+          { "type": "click", "selector": "[data-testid=confidence-4]" }
+        ]
+      }
+    },
+    {
+      "id": "demo-schedule",
+      "start": 300,
+      "duration": 240,
+      "vo": "That confidence score adjusts your next review date live, so easy cards fade back and hard ones come around sooner.",
+      "visual": {
+        "captureMethod": "recording",
+        "url": "https://app.loomcard.example/review",
+        "interactions": [
+          { "type": "click", "selector": "[data-testid=confidence-1]" },
+          { "type": "wait", "ms": 600 }
+        ]
+      }
+    },
+    {
+      "id": "cta",
+      "start": 540,
+      "duration": 180,
+      "vo": "Loomcard is free and open source. Star it, try it, or send a pull request.",
+      "visual": {
+        "captureMethod": "dom-demo"
+      }
+    }
+  ]
+}
+```
+
+Note the `demo-schedule` beat: the CSV/Anki import feature from intake was
+dropped, not shown, because it isn't wired up yet and no real capture or
+honest `dom-demo` was worth building for a roadmap item this early in the
+pitch. A beat that claimed it anyway would have failed the
+claim-obligates-visual rule (`SCRIPT.md`). The `cta` beat uses `dom-demo`
+because `RepoCta` is a hand-authored scene built from real repo data, not
+a captured screenshot of anything.

package/docs/SCRIPT.md

@@ -0,0 +1,50 @@
+# SCRIPT.md: VO pacing and writing rules
+
+VO for every video should sound like the same person wrote it: direct,
+confident about what's actually shown, never claiming more than the visual
+backs up.
+
+## Pace
+
+Target **~2.3-2.9 words/sec**. This is edge-tts's natural reading pace at
+default settings, the actual ratio observed across this pipeline's
+production use, not a theoretical number. If you're writing VO for a beat
+of known duration, word-count budget equals `duration_seconds * pace`;
+stay inside that range rather than writing to a "feels about right" length
+and hoping it fits.
+
+## Duration formula
+
+When a beat's duration is being derived from its VO (rather than the other
+way around):
+
+```
+duration = (VO word count / pace) + pad
+```
+
+Use a pad of **0.3-0.6s**. The pad exists so the visual doesn't cut the
+instant speech ends: a beat that ends exactly when the last word does
+reads as clipped, and a small buffer lets the shot breathe for a moment
+before the cut.
+
+## The claim-obligates-visual rule
+
+If a beat's VO asserts the product does something, the visual must back it
+up: either a real capture (`screenshot`/`recording`) of the product
+actually doing it, or an explicitly labeled `dom-demo` mockup built for a
+feature that isn't wired up yet. Never let VO overclaim past what's on
+screen. If the visual can't back a sentence, rewrite the sentence, don't
+leave it in and hope no one checks.
+
+This is the same rule `PIPELINE.md` states for beat authoring generally;
+here it's specifically about VO, because VO is usually written first and
+is where an overclaim first gets introduced. Use `PLANNING.md`'s
+per-feature capture-method decision tree to decide, for each claim,
+whether it needs a real capture or an honest `dom-demo`. Don't write a
+claim the decision tree can't resolve to something real or
+explicitly-labeled-constructed.
+
+## No em dashes
+
+No em dashes in any VO line, ever, same writing rule as every other doc in
+this pipeline. Use commas, periods, or a rewritten sentence instead.

package/docs/STYLE.md

@@ -0,0 +1,88 @@
+# STYLE.md: Art Direction Bible
+
+Binding rules for every video built with openvidstudio. If a scene violates
+a rule here, it fails QC.
+
+## What good cinematography for this pipeline looks like (decoded)
+
+1. **Camera lives INSIDE the UI.** Never show a flat full-screen
+   screenshot. The camera is always zoomed into a region (120-250% scale),
+   slightly tilted (1-4 degrees rotateZ, 2-8 degrees rotateX/Y
+   perspective), and moving (push-in, drift, pan). UI is rendered oversized
+   on a stage; the camera crops into it.
+2. **Shallow depth of field.** One focal plane per shot. Everything else
+   (background layers, edge regions, sidebars) carries gaussian blur.
+   Focus can rack between layers mid-shot.
+3. **Low-key lighting.** Dark scenes: deep vignette, soft glow accents on
+   the key element (accent-colored text-shadow/box-shadow). Light scenes:
+   soft large-radius drop shadows, floating cards, generous negative
+   space.
+4. **Cursor is an actor.** Oversized cursor, eased movement (never
+   linear), click = ripple ring + glow pulse on the target. Buttons
+   visibly react.
+5. **The montage shot.** Isometric-tilted grid of floating UI windows,
+   depth-stacked, edges blurred, slow drift. Used for hooks/outros.
+6. **Warm/cool contrast.** Cool UI (blues, slate) against warm accent
+   lighting or warm desk tones.
+7. **Motion never stops.** Every shot has at least a subtle push-in (2-5%
+   scale over the shot). Static frame = dead frame = QC fail.
+
+## Hard rules
+
+- NO linear easing. Ever. Use `@openvidstudio/core`'s `E.*` presets
+  (cinematic bezier / springs).
+- Every scene wrapped in `CinematicScene` (grain + vignette + grade always
+  on).
+- **On-screen text and UI is real by provenance, not by medium.** The
+  earlier version of this rule was "all text is DOM text," reasoned from
+  medium: anything not literally re-rendered as DOM inside the composition
+  wasn't trusted. That rule was a refinement waiting to happen: a genuine
+  screen recording of the real, running product isn't AI-hallucinated,
+  it's ground truth exactly like a screenshot is, so a medium-based rule
+  would have wrongly forbidden a legitimate capture method. The restated
+  rule: real product UI/text, whether DOM-rendered, screenshotted, or
+  screen-recorded, is always allowed on screen, because it's ground truth
+  by provenance. Screenshots may only appear inside `BrowserFrame`;
+  recordings composite as an `OffthreadVideo` inside a `Layer`, the same
+  camera-keyframe pattern. Both are captured per `CAPTURE.md`'s protocol
+  (a plain "set DPR to 2x" isn't enough on its own; the Playwright profile
+  can carry a per-origin zoom desync that silently shrinks/misframes an
+  uncompensated capture, and `CAPTURE.md`'s viewport-compensation plus
+  DOM-rect-crop steps are the actual fix). AI-generated clips (Higgsfield
+  or any future model) never carry on-screen product text or real UI:
+  b-roll/atmosphere only, see `HIGGSFIELD.md`.
+- One focal point per shot. If two things matter, that's two shots.
+- Text enters via mask reveal / clip-path wipe / per-word stagger, never
+  plain opacity fade.
+- Cut rhythm: shots 1.5-5s. Hold longer only when content itself animates
+  (typing, install cascade).
+- Terminal is always `TerminalReplay` (DOM), never screen-recorded HTML.
+- SFX on every interaction: keystrokes (low volume 0.12-0.2), UI blips on
+  reveals, whoosh on camera moves/cuts, click ring + click sound together.
+- Shot list per video lives in the video's own brief; camera keyframes
+  reference it.
+
+## Palette + type (defaults; per-video themes may override)
+
+- Stage/dark bg: #0B0E14 to #11151F radial. Panel: #151A24. Border:
+  #232B3A.
+- Text: #E6EAF2 primary, #8A94A6 secondary.
+- Accent: #4E9EFF (cool blue) + #9D6BFF (violet), glow accents. Success:
+  #3ECF8E. Warn: #F5A623.
+- Light scenes: bg #F4F6F9, cards #FFFFFF, shadow rgba(15,23,42,0.12)
+  large radius.
+- Fonts: Inter (UI), JetBrains Mono (terminal/code) via
+  `@remotion/google-fonts`.
+- Grain: 4-6% opacity, animated (re-seeded translate per frame). Vignette:
+  25-40% edge darkening.
+
+## Deferred (do not attempt in pure Remotion)
+
+- Live-action beats (desk/keyboard shots, ambient texture): text-free, so
+  these are the Higgsfield/AI-footage slot; see `HIGGSFIELD.md`. Still skip
+  by default: design scenes so they aren't needed unless a brief
+  specifically calls for a live-action beat, and never let an AI-generated
+  clip carry on-screen product text or real UI.
+- Music beds (added with VO in post, or looped under a baked-in VO mix,
+  see `SCRIPT.md`). Chromatic aberration + real bloom passes (perf;
+  revisit).

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@openvidstudio/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server exposing openvidstudio's mechanical pipeline tools: project scaffolding, beats validation, scene stubs, composition stitching, render, QC frame extraction, and zoom-compensated screenshot/screen-recording capture.",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "bin": {
+    "openvidstudio-mcp": "dist/stdio.js"
+  },
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "files": [
+    "dist",
+    "templates",
+    "docs"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "playwright": "^1.48.0",
+    "sharp": "^0.33.5",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "node scripts/copy-template.mjs && node scripts/copy-docs.mjs && tsc",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "node scripts/manual-test.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnayDhawan/openvidstudio.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/AnayDhawan/openvidstudio#readme",
+  "bugs": {
+    "url": "https://github.com/AnayDhawan/openvidstudio/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "remotion",
+    "playwright",
+    "video",
+    "demo-video",
+    "claude"
+  ]
+}

package/templates/default/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md: this project's video pipeline
+
+This project was scaffolded with openvidstudio: a Remotion + Playwright
+video-generation add-on driven via MCP tools. If you're an AI coding agent
+about to build a video for this project, read `PLANNING.md` first. That's
+step 0, before you touch `beats.json` or write a single scene.
+
+## Docs
+
+`init_project` copies these into this project's own `docs/` directory
+when it scaffolds the project shell (it never overwrites a file you've
+already edited, so a second `init_project` call for a second video won't
+clobber local edits here). If a doc listed below is missing, re-run
+`init_project` rather than guessing where it lives.
+
+- `./docs/PLANNING.md`: start here. Guided intake to beats.json protocol,
+  capture-method decision tree, the mandatory approval gate.
+- `./docs/PIPELINE.md`: beats.json, scenes, composition, QC loop.
+- `./docs/STYLE.md`: binding art-direction rules.
+- `./docs/CAPTURE.md`: real-screenshot protocol.
+- `./docs/SCRIPT.md`: VO pacing and writing rules.
+- `./docs/OVERVIEW.md`: conceptual overview; read this if you're unsure
+  why any of the rules below exist.
+- `./docs/HIGGSFIELD.md`: AI b-roll tier protocol.
+- `./docs/API.md`: every prop of every `@openvidstudio/core` component. Read
+  this instead of opening the library source.
+- `./docs/NARRATION.md`: voice, music and sound effects, and why generated
+  voiceover usually sounds synthetic.
+
+## Rules a scene-writing agent must never violate
+
+These are QC-fail rules, not defaults, pulled from `STYLE.md` and
+`PIPELINE.md` and restated here because they're the ones most likely to get
+silently broken while writing a scene:
+
+- **No linear easing, ever.** Use the eased/spring presets
+  `@openvidstudio/core` exports from its motion helpers. A static,
+  non-eased move fails QC.
+- **Every scene wrapped in `CinematicScene`.** No screen ever renders
+  outside it (grain, vignette, and grade are always on).
+- **Motion never stops.** Every shot needs at least a subtle push-in. A
+  frozen frame is a QC fail.
+- **No em dashes**, on screen or in VO, anywhere.
+
+## Before you hand-write a scene
+
+`scaffold_scene` emits a scene that renders, using that beat's own copy and
+duration. Start from it and edit the content rather than composing a scene
+from primitives: it already has correct camera keyframes, a safe content
+width, and the right shape for the beat's capture method.
+
+Then run `validate_scenes`. The commonest mistake in this pipeline is
+invisible: content laid out at full stage width gets cropped once the camera
+pushes in, and the render does not warn.
+
+## Components
+
+Reach for `@openvidstudio/core`'s components before building anything new:
+`CinematicScene`, `CameraRig`/`Layer`, `BrowserFrame`, `TerminalReplay`,
+`CodePanel`, `ChecklistPanel`, `CursorActor`, `RepoCta`,
+`TitleSlam`/`Caption`. Only build a new component when a beat truly needs
+one, then keep it generic: it's a candidate for `@openvidstudio/core`
+itself, not just this project.

package/templates/default/openvidstudio-core/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@openvidstudio/core",
+  "version": "0.1.0",
+  "description": "Camera rig, motion, SFX, look pass, and scene components shared by every openvidstudio video project.",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "scripts",
+    "public"
+  ],
+  "dependencies": {
+    "@remotion/google-fonts": "^4.0.490"
+  },
+  "peerDependencies": {
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "remotion": "4.0.490"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.7",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "remotion": "4.0.490",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnayDhawan/openvidstudio.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/AnayDhawan/openvidstudio#readme",
+  "bugs": {
+    "url": "https://github.com/AnayDhawan/openvidstudio/issues"
+  },
+  "keywords": [
+    "remotion",
+    "video",
+    "demo-video",
+    "screencast",
+    "mcp"
+  ]
+}

package/templates/default/openvidstudio-core/scripts/gen-sfx.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# Generate synthesized UI SFX into public/sfx/ (no licensing, fully reproducible).
+# Swap any file for a real recorded pack later, sfx.tsx API stays identical.
+set -e
+cd "$(dirname "$0")/.."
+mkdir -p public/sfx
+
+# Mechanical key thocks: filtered brown-noise bursts, 3 pitch variations
+ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.06:c=brown:a=0.9" \
+  -af "highpass=f=180,lowpass=f=2400,afade=t=in:d=0.004,afade=t=out:st=0.025:d=0.035,volume=3.2" \
+  public/sfx/key_a.wav
+ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.055:c=brown:a=0.9:seed=7" \
+  -af "highpass=f=200,lowpass=f=1900,afade=t=in:d=0.004,afade=t=out:st=0.022:d=0.033,volume=3.4" \
+  public/sfx/key_b.wav
+ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.065:c=brown:a=0.9:seed=23" \
+  -af "highpass=f=160,lowpass=f=2900,afade=t=in:d=0.004,afade=t=out:st=0.028:d=0.037,volume=3.0" \
+  public/sfx/key_c.wav
+
+# Click: sharp short tick
+ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.03:c=white:a=0.8" \
+  -af "highpass=f=1400,lowpass=f=6500,afade=t=in:d=0.002,afade=t=out:st=0.01:d=0.02,volume=2.2" \
+  public/sfx/click.wav
+
+# Whoosh: bandpassed pink noise swell
+ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.55:c=pink:a=0.8" \
+  -af "bandpass=f=650:w=500,afade=t=in:d=0.18,afade=t=out:st=0.25:d=0.3,volume=2.6" \
+  public/sfx/whoosh.wav
+
+# Blip: soft sine tick for UI reveals
+ffmpeg -v error -y -f lavfi -i "sine=frequency=740:duration=0.07" \
+  -af "afade=t=in:d=0.008,afade=t=out:st=0.03:d=0.04,volume=0.9" \
+  public/sfx/blip.wav
+
+# Success: rising two-tone
+ffmpeg -v error -y \
+  -f lavfi -i "sine=frequency=660:duration=0.09" \
+  -f lavfi -i "sine=frequency=990:duration=0.14" \
+  -filter_complex "[0]afade=t=out:st=0.05:d=0.04[a];[1]afade=t=in:d=0.01,afade=t=out:st=0.08:d=0.06[b];[a][b]concat=n=2:v=0:a=1,volume=0.9" \
+  public/sfx/success.wav
+
+echo "SFX generated:"
+ls public/sfx/
+
+# Bell: struck metallic tone, harmonic stack with a long decay
+ffmpeg -v error -y \
+  -f lavfi -i "sine=frequency=1568:duration=1.6" \
+  -f lavfi -i "sine=frequency=2350:duration=1.6" \
+  -f lavfi -i "sine=frequency=3136:duration=1.6" \
+  -filter_complex "[0]volume=1.0[a];[1]volume=0.45[b];[2]volume=0.22[c];[a][b][c]amix=inputs=3:normalize=0,afade=t=in:d=0.004,afade=t=out:st=0.12:d=1.45,volume=1.2" \
+  public/sfx/bell.wav
+
+# Enter key: deeper, heavier thock than a letter key
+ffmpeg -v error -y -f lavfi -i "anoisesrc=d=0.085:c=brown:a=0.95:seed=41" \
+  -af "highpass=f=110,lowpass=f=1500,afade=t=in:d=0.004,afade=t=out:st=0.03:d=0.05,volume=3.6" \
+  public/sfx/key_enter.wav
+
+# Music bed: slow ambient pad, two detuned sines under a filtered noise wash.
+# Synthesized rather than licensed, so a generated video carries no third-party
+# audio rights. 60s, loop it for longer videos.
+ffmpeg -v error -y \
+  -f lavfi -i "sine=frequency=110:duration=60" \
+  -f lavfi -i "sine=frequency=164.81:duration=60" \
+  -f lavfi -i "sine=frequency=220.5:duration=60" \
+  -f lavfi -i "anoisesrc=d=60:c=pink:a=0.06" \
+  -filter_complex "\
+    [0]volume=0.34,tremolo=f=0.11:d=0.30[p1];\
+    [1]volume=0.20,tremolo=f=0.13:d=0.26[p2];\
+    [2]volume=0.13,tremolo=f=0.17:d=0.35[p3];\
+    [3]lowpass=f=900,volume=0.5[air];\
+    [p1][p2][p3][air]amix=inputs=4:normalize=0,\
+    lowpass=f=2600,afade=t=in:d=3,afade=t=out:st=56:d=4,volume=0.5" \
+  -c:a libmp3lame -q:a 5 public/sfx/music-bed.mp3
+
+echo "generated: $(ls public/sfx | wc -l) files in public/sfx/"