suggest-sfx

suggest-sfx — the SFX pass

Take a rendered, voiced short and add tasteful sound effects, synced to the visual beats and the narration, drawn from a shared, growing SFX library. Work collaboratively and beat-by-beat; the user audits the plan and gives notes.

The shape: a declarative plan (sfx-plan.json) is the source of truth → a tool consumes it (tools/mix_sfx.py) → a library grows (media/library/sfx/) → a hard USER-AUDIT gate before anything is mixed.

Sound taste is a brand contract — read brand.md §7 every time. The house style is calm/premium (Linear / Anthropic / Vercel), felt-not-heard, always under the voice. NOT MrBeast-loud.

Inputs (read these first, every session)

• brand.md §7 (Sound design) — the SFX taste contract: subtlety, density, palette, levels, sync, signature motifs, source policy. Non-negotiable.
• shorts/short-N-<niche>/beats.json — the beats and REAL per-word voice times (written back by gen_voice.py). Sync cues to these words (a pop on "boom", a chime on "free").
• The shot source remotion/src/shots/short-N/*.tsx — the INTERNAL animation frames are where the real visual beats are (piece lands, digit pops, badge stamps). Read the shot, convert its local frame to global time: at_s = (local_frame + sequence_from) / fps. Do not guess — the cue must land on the exact frame the thing happens.
• media/library/sfx/catalog.json + palette.json — the library you draw from and grow.

The library (media/library/sfx/) — the durable asset

• palette.json — generation recipes: generic, reusable sound ids + prompts + duration + tags. The source of truth for what the library SHOULD contain.
• catalog.json — the manifest of what EXISTS: {id, file, category, tags, duration_s, peak_dbfs, loudness_lufs, source, model, license, prompt, used_in} per clip. Written by gen_sfx.py.
• clips/*.mp3 — loudness-normalized clips (~−20 LUFS, −1.5 dBFS ceiling) so a plan's per-cue gain_db is perceptually meaningful.
• Library-first, always. Reuse an existing clip before generating. Name/tag clips GENERICALLY (ui-toggle-on, whoosh-soft, pop-reveal) so future videos reuse them — the library is the durable asset, each video is one draw from it. Only genuinely-missing sounds get added to palette.json and generated.