Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Video & audio

suggest-sfx

The SFX pass. Analyze a short's beats + narration and propose tasteful sound effects synced to them, drawing from (and growing) a shared, reusable SFX library, then render an SFX-mixed audition preview. Use when the user wants to "add SFX / sound effects", "suggest sfx", "score the transitions", "sound-design this beat", generate/source sound effects, build or extend the sfx library/catalog, author or audit a sfx-plan, or mix SFX over a rendered short in this repo. Covers reading beats + word times + brand §7, the library-first flow, generating misses with the ElevenLabs Sound Effects API, the per-video sfx-plan.json, the hard user-audit gate, and mixing with tools/mix_sfx.py (light voice ducking).

hassancs91 · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add hassancs91/claude-faceless-shorts-creator --skill suggest-sfx

About this skill


name: suggest-sfx description: The SFX pass. Analyze a short's beats + narration and propose tasteful sound effects synced to them, drawing from (and growing) a shared, reusable SFX library, then render an SFX-mixed audition preview. Use when the user wants to "add SFX / sound effects", "suggest sfx", "score the transitions", "sound-design this beat", generate/source sound effects, build or extend the sfx library/catalog, author or audit a sfx-plan, or mix SFX over a rendered short in this repo. Covers reading beats + word times + brand §7, the library-first flow, generating misses with the ElevenLabs Sound Effects API, the per-video sfx-plan.json, the hard user-audit gate, and mixing with tools/mix_sfx.py (light voice ducking).

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.

Workflow

  1. Read brand §7 + beats.json + the shot source + catalog. Pull exact cue times: for each candidate beat, find the visual moment's local frame in the shot and/or the narration word, and convert to global seconds.
  2. Decide taste with the user up front if unsettled (present-ness, density, which kinds, source) — then apply brand §7. Don't re-ask settled decisions.
  3. Propose the cue list — function-first. For each beat ask what it needs (brand §7): motion (whoosh) · tension (riser) · emphasis (impact/pop) · snap (click). Score key transitions, reveals, and tasteful click-sequences; a 3–4-shot click-sequence counts as ONE gesture. Mark genuinely deniable texture as "optional": true. Layer the 2–3 biggest moments (build-and-drop): riser→impact on a scripted reveal, whoosh→pop so a cut stands out — in the plan a layer is two events at the same/adjacent at_s that sum. Sync each cue to the VISUAL beat and often the exact word.
  4. Library-first sourcing. For each distinct sound the plan needs, reuse a catalog clip if one fits. For misses, add a generic recipe to palette.json and generate: python tools/gen_sfx.py (ElevenLabs Sound Effects API → normalized clip → catalog). Fall back to curated royalty-free only where generation is weak; record source + license either way.
  5. Author shorts/short-N-<niche>/sfx-plan.json — one event per cue, at_s in global seconds. (Schema below.)
  6. USER-AUDIT GATE (hard). Present the resolved cue sheet (python tools/mix_sfx.py <plan> --print) and get the user's approval/notes BEFORE mixing.
  7. Mix the audition preview once approved: python tools/mix_sfx.py shorts/short-N-<niche>/sfx-plan.json → the plan's render.out. Light sidechain duck under the voice + a safety limiter. Iterate on the user's notes (gains, timing, add/cut cues) — re-print, re-mix.
    • Verify audibility with numbers, not hope. After mixing, RMS-diff the mixed audio vs the voice-only preview at each cue window: a story-critical cue should add ≥ +4 dB, texture +1–3 dB. Inaudible cues hide in cue sheets — don't ship a cue you haven't confirmed lands.
    • Transient-clip gain gotcha. Short percussive clips (knock/stamp/keys/snap) hit the −1.5 dBFS peak ceiling BEFORE reaching the −20 LUFS loudness target, so they catalog ~3–5 dB quieter than sustained clips. Their plan gain_db must be ~3–5 dB higher than the brand table implies. The audibility check above is what surfaces this.
    • SHORTS calibration. Under a short's near-continuous narration (~2.7 w/s, few gaps) a conservative gain table is 4–8 dB too quiet across the board — the duck + voice masking eat everything. Proven landing zone: transitions/whooshes −3, story pops/impacts 0..+3,
Read the complete source ↗