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
- OpenRootdev/sfx-tooltheir own version, first seen Nov 16, 2026
- neskuchny/content_factorytheir own version, first seen Nov 16, 2026
- NachoEstevo/audiofxtheir own version, first seen Nov 15, 2026
- EditAtlas/skillstheir own version, first seen Nov 15, 2026
- krusemediallc/video-editor-agenttheir own version, first seen Nov 12, 2026
- killerwolf/skillstheir own version, first seen Nov 8, 2026
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- krusemediallc/video-editor-agent★ 168same name
- mrpaidsocial/mrpaidsocial-video-editor-agent★ 168same name
- EditAtlas/skills★ 40same name
- ridelink0/ultimate-frontend-skills★ 7same name
- badgids/Story-Film-Skills★ 4same name
- Razee4315/coldframe★ 4same name
- zane-tv/holdframe★ 2same name
- killerwolf/skills★ 1same name
- neskuchny/content_factory★ 1same name
- BlackAngel242/skill-market★ 0same name
3 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- image-generationSkill
- scriptwritingSkill
- video-directorSkill
- voice-directionSkill
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
- Distinctive: line 44
Licences: keep music and SFX licences in a ledger.
- Very specific: line 53
Write cues.json (by hand, or exported from a video timeline) with one cue per animated event (tick runs and typing marked "role": …
“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.
Files
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.
| 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
- With a voice, the voice is the clock; edit the music around it. Without one, pick the music first and build on its grid.
- 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.
- 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.
- 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.pyfails 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. - 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.
- Mix offline for finals: one cue list, stems, two-pass loudnorm. Measure the encoded file, not just the WAV.
- Sound comes after picture lock; derive cue times from the same timeline the picture uses so re-timing is free.
- Licences: keep music and SFX licences in a ledger; licensed tracks stay out of git (URL in the README).
Workflow
- 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). music_analyze.pyon the clean track: tempo, bars, key, energy, drop candidates; refine with--around.- Edit with
music_splice.py(rank, render), thenblindexcerpts formedia_judge.py blind-splice. - Generate missing sounds with
foley.py --key <song key>. - 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 runmix.py; fix every SFX audibility failure and warning; check sync points withaudio_qa.py --envelope. - 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.pykinds: pop, blip, thump, slap, stamp, whoosh, swell, tear, tick, key, flip, pluck, chime, riser, bass-hit, shimmer, reverse-swoosh. Deterministic per kind and variant; writessfx-manifest.jsonwith each file's peak offset. Risers and reverse swooshes peak near their end, so with peak alignment they end onat: 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 linearwhen both sides are near-identical (equal-power adds +3 dB there).mix.py: schema inscripts/cues.schema.md(--print-schemafor 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.pySFX 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.
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
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.

