agentleFS
salomonMurielsalomonMuriel/media-production-skills/skills/sound-design/SKILL.md

sound-design

Skill1 starsChanged 41 days agoMITView on GitHub

Music, sound effects, mixing and loudness for podcasts, apps and games (app UI sounds, podcast mixes, audio files). 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". Not for sound in videos: video-director uses the cinetic skill's score workflow for that.

13 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 11 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Licences: keep music and SFX licences in a ledger.

    line 44
  2. Very specific:

    Write cues.json (by hand, or exported from a video timeline) with one cue per animated event (tick runs and typing marked "role": …

    line 53

“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Sound design

For sound and music in a video, use the cinetic skill's sound workflow (references/sound.md) instead of this skill.

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.

TopicFile
Choosing music, analysis, the drop, beat grids, edits, blind splice tests, AAC offsetreferences/music.md
SFX placement by transient, genre-appropriate sound, density, foley, Remotion volume gotchasreferences/sfx.md
Ducking, the offline mix from cues.json, loudness and mastering, diagnosing a voicereferences/mix.md
The cues.json schema for mix.pyscripts/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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.