Sound Design

---
name: sound-design
description: Music, sound effects, mixing and loudness for video, podcasts, apps and games. Chooses and analyses music (tempo, bars, key, energy, finding the drop), edits it on bars with blind listening tests, syncs picture to beats, places SFX by their measured transient, synthesises a deterministic foley and UI sound kit tuned to the song's key, ducks music under voice, mixes offline from a cue list into stems and a master, and masters to platform loudness (-14 LUFS / -1 dBTP for social, -16 for podcasts) measured on the final file. Use it whenever the user wants to pick, cut, sync or score music, add or design sound effects or UI sounds, mix voice and music, fix levels or loudness, or check how a file measures, even if they don't say "sound design". The video-director skill calls it at its sound gate.
---

# Sound design

Sound is half of perceived quality. You can't hear, so every decision rests on measurements (LUFS, true peak, envelopes,
onsets) plus an audio-capable judge model or the user's ears for the important calls.

## Step 0: read every file before the first action

This skill is loaded whole, never in part. Read this `SKILL.md` to the end, then every file in the table below, each to
its last line: no `offset`/`limit`, no `head`, `grep` or skimming, no "only the sections this task needs". If a read comes
back truncated, keep reading until the file ends. The task decides what you apply, never what you read; the table says
where each topic lives, not which files to skip. This holds when the skill is called on its own, from `video-director`, or
by a sub-agent. If the context is summarised mid-task, read the set again before the next action that depends on it.

| Topic | File |
|---|---|
| Choosing music, analysis, the drop, beat grids, edits, blind splice tests, AAC offset | `references/music.md` |
| SFX placement by transient, genre-appropriate sound, density, foley, Remotion volume gotchas | `references/sfx.md` |
| Ducking, the offline mix from `cues.json`, loudness and mastering, diagnosing a voice | `references/mix.md` |
| The `cues.json` schema for `mix.py` | `scripts/cues.schema.md` |

## Principles

1. **With a voice, the voice is the clock**; edit the music around it. Without one, pick the music first and build on its grid.
2. **Find the drop by measuring energy**, never by trusting an auto beat grid (one was two beats off; a tracker's tempo was 2%
   off). Fit the grid yourself and land the key moment on the drop.
3. **Cut music on bars** with a short equal-power crossfade, and give every splice a blind test against an untouched control.
   The song's own ending ("button") beats a fade or a cut into a sparse outro.
4. **Every animated event gets a sound**, or a logged reason for silence, and the sound must be heard: event cues sit
   at gains of 0.3 to 0.6 (hero hits up to 1), and `mix.py` fails a mix whose events sit, at the median, more than
   12 dB under voice plus music. Place SFX by the transient peak, not the file start; subtract the render's audio
   offset (AAC priming, ~1.3 frames at 30 fps). Choose sounds by genre; tuned foley in the song's key is the
   signature; never meme sounds or stock game-pack samples in brand work.
5. **Duck the bed 8 to 15 dB under the voice** with a slow release and, where possible, a dip at 1 to 3 kHz; keep the
   sidechain voice-only.
6. **Mix offline for finals**: one cue list, stems, two-pass loudnorm. Measure the encoded file, not just the WAV.
7. **Sound comes after picture lock**; derive cue times from the same timeline the picture uses so re-timing is free.
8. **Licences**: keep music and SFX licences in a ledger; licensed tracks stay out of git (URL in the README).

## Workflow

1. Shortlist 20 to 50 tracks; audio-model listening round with a fixed card (`media_judge.py music-fit`), chunk descriptions for
   finalists (`media_judge.py chunks`).
2. `music_analyze.py` on the clean track: tempo, bars, key, energy, drop candidates; refine with `--around`.
3. Edit with `music_splice.py` (rank, render), then `blind` excerpts for `media_judge.py blind-splice`.
4. Generate missing sounds with `foley.py --key <song key>`.
5. Write `cues.json` (by hand, or exported from a video timeline) with one cue per animated event (tick runs and typing
   marked `"role": "texture"`) and run `mix.py`; fix every SFX audibility failure and warning; check sync points with
   `audio_qa.py --envelope`.
6. Master check on the final file: `audio_qa.py final.mp4`.

## Scripts

**Paths:** scripts live in this skill's `scripts/` folder, under the base directory shown when the skill loads (`~/.claude/skills/sound-design/` for a standard install; a plugin install puts it elsewhere). The other skills of this suite sit next to it as sibling folders. Paths written as `~/.claude/skills/...` below assume the standard install.

uv scripts with `--help`; path `~/.claude/skills/sound-design/scripts/`. Shared helpers in `lib_audio/`. ffmpeg is resolved as
`$FFMPEG`, then PATH, then imageio-ffmpeg.

```
foley.py [kinds...|all] [--key F] [--notes 0,5,7] [--length S] [--variants N] [--seed 7] [--out public/sfx]
music_analyze.py <track> [--around T ...] [--downbeat T] [--grid steady|tracked] [--beats-per-bar 4] [--drops 5] [--out-dir out]
music_splice.py rank <track> --beats out/<track>.beats.json (--cut A | --entry B | --target-length S) [--top 8]
music_splice.py render <track> --segments 0:70.915,172.047:173.75 [--fade-ms 12] [--curve power|linear] [--out out/music-edit.wav]
music_splice.py blind out/music-edit.wav --source <track> [--length 8] [--controls 1] [--out-dir out/review/splice-blind]
mix.py out/cues.json [--root public] [--out out/mix.wav] [--stems out/stems] [--key F] [--vo-lufs -16] [--music-lufs -19]
    [--duck-db 6] [--duck-high-db 3] [--attack 0.08] [--release 0.6] [--lufs -14] [--true-peak -1] [--check] [--print-schema]
audio_qa.py <file> [file ...] [--target-lufs -14] [--max-true-peak -1] [--envelope START END [STEP]] [--spans]
    [--check-silence t1,t2] [--report-only] [--json]
```

- `foley.py` kinds: pop, blip, thump, slap, stamp, whoosh, swell, tear, tick, key, flip, pluck, chime, riser, bass-hit,
  shimmer, reverse-swoosh. Deterministic per kind and variant; writes `sfx-manifest.json` with each file's peak offset. Risers
  and reverse swooshes peak near their end, so with peak alignment they end on `at`: put that on the cut.
- `music_analyze.py`: run it on the clean music, never the mix (it warns when tracked beats agree with the steady grid less
  than 50% of the time). The first run takes minutes while uv fetches librosa's dependencies.
- `music_splice.py`: crossfades are centred on the join; use `--curve linear` when both sides are near-identical (equal-power
  adds +3 dB there).
- `mix.py`: schema in `scripts/cues.schema.md` (`--print-schema` for JSON Schema). Stems are written before mastering; a
  look-ahead true-peak limiter runs before loudnorm so ffmpeg stays in linear mode (the report says which mode ran). Exits 2
  when the master misses −14 ±0.5 LU, exceeds −1 dBTP, or its event SFX sit at a median more than 12 dB under voice
  plus music (`--sfx-median-db`; per-cue warnings below −20 dB, `--sfx-cue-db`). Calibrated on the Repitis film (−8 dB)
  against one that sounded flat (−25 dB).
- `audio_qa.py`: allows 0.05 dB of true-peak measurement slack (a mix normalised to exactly −1 dBTP measures −0.99).
- Judge models (music fit, chunk descriptions, blind splice tests):
  `~/.claude/skills/video-director/scripts/media_judge.py` (OpenRouter).

## Checklist

- [ ] The voice is the clock (if any); the music drop is on the key moment; cuts on beats within 3 to 4 frames.
- [ ] Bed ducked under every voice, slow release, open at t=0.
- [ ] Every animated event has a cue or a logged silence; `mix.py` SFX audibility passes with no unexplained warnings.
- [ ] SFX peaks on contact frames, offset compensated; no meme sounds; foley in key.
- [ ] Every music splice passed a blind test with a control.
- [ ] −14 LUFS (or the platform target) and ≤ −1 dBTP measured on the final encoded file.
- [ ] Licences recorded; licensed music out of git.