/real-sound

name: real-sound
description: Build premium, realistic soundtracks for code-made videos and animations from real licensed recordings - launch films, product and feature videos, UI walkthroughs, logo stings, explainers, trailers and animated shorts made with Remotion, HyperFrames, three.js, GSAP or any renderer. Use this whenever a video or animation needs sound design, SFX, foley, ambience, music, a soundtrack, a score, UI click / whoosh / riser / impact / logo-sting sounds, or a music edit to picture; whenever a synthesized or "random" sounding soundtrack must be replaced with real recordings; or when the user asks to source, license, credit, mix, master, critique or mux audio for a film. It covers cue lists from the picture, sourcing from Freesound / Mixkit / composer libraries with licence checks, a music edit at bar lines, a JSON sound design rendered by a deterministic mixer, measured QA (clicks, masking, harshness, sync, loudness) plus earshot listening, a multi-agent critique, mastering, credits and the mux.

real-sound

You are the sound supervisor of a film you cannot hear. The soundtrack is built ONLY from real, professionally recorded or produced audio (one licensed music track, real foley and SFX, real ambiences), placed on the picture's cue frames by a deterministic mixer, measured instead of listened to, critiqued through five lenses, fixed by one agent, mastered, credited and muxed. Code selects, trims, places, levels, pans, EQs, pitches by resampling, time-stretches the music and masters; code never generates a sound.

The bar is a professional launch film: every sound caused by something on screen, one material palette, the music's drop on the hero reveal, restraint everywhere else, a resolved logo, a tail into silence. Rules: `references/sound-design.md` (and the earshot repo's `docs/launch-video-sound.md` for the bundled reference profile: 7 professional launch films).

`<skill>` below is this folder. **Python:** `{{PY}}` below (and in every prompt template) is ONE interpreter that has numpy, scipy, soundfile and the earshot package: the earshot repo's venv (`<earshot repo>/.venv/Scripts/python.exe` on Windows, `<earshot repo>/.venv/bin/python` elsewhere), or any Python where `<python> -c "import earshot"` works. Bare `python` on Windows is often the Microsoft Store stub and fails. Substitute the full path for `{{PY}}` when you run a command or hand a prompt to a sub-agent (the other placeholders are listed in `references/process.md`). Run the scripts with `-I` (isolated: downloaded files can never shadow a module); every script except `scripts/licences.py` (the licence policy module that audit.py and credits.py import) prints `--help`.

The process

| step | who | output | gate | |---|---|---|---| | 0. cue list | lead | `out/cues.json` | sync frames computed from the picture code | | 1. brief | lead | `audio/SOUND_BRIEF.md` | every cue has a sound need (or "nothing") | | 2. sourcing (per category, parallel) | sourcing agents | `audio/assets/<cat>/`, manifests | each file measured + earshot `realness` "real or pro-produced" on the trim used (an "uncertain" only with its evidence and a trim-level re-check written in the manifest) | | 3. licence audit | auditor | `audit.json` | `audit.py` exit 0 for what the film uses | | 4. music edit | music supervisor | `audio/design/music.json` | grid verified, drop on the reveal, splices clean | | 5. design fragments (per category, parallel) | designers | `audio/design/<cat>.json` | solo render + qa clean | | 6. integrate | lead | soundtrack, stems, report, trace | master gate (+-0.5 LU, <= -1.5 dBTP) | | 7. QA + listening | lead | `out/qa/qa.json`, earshot timeline / sheet / critique | no qa fail | | 8. critique (5 lenses, parallel, read-only) | critics | ranked issues + tested operations | | | 9. fix | ONE fixer | the design | qa: no regression | | 10. master, credits, mux | lead | `CREDITS.md`, description text, the film | credits exit 0, lag 0 |

The detail of every step, the roles and what each critic measures: `references/process.md`. Every sub-agent prompt is a ready-to-fill brief in `templates/prompts/`.

0. Cue list from the picture

Every sound sits on a frame the picture code computes: a contact frame, a pop-in's 50 % frame, a move's velocity peak, a riser's hit, the frame the wordmark becomes readable. Cinetic films already have `out/cues.json` (`export-cues.ts`); for anything else write the same format (`templates/cues.json`) from the timeline constants. Stable ids (`act:thing:n`) let rules match classes of action with a regex.

1. Brief

Copy `templates/SOUND_BRIEF.md` to `audio/SOUND_BRIEF.md`: concept (palette, the music's arc, places), the picture map (every cue: what is on screen, the sound need), ambience zones, allowed licences, quality bar, file layout. It is the contract every sub-agent gets verbatim. Pick the brand's personality row (`references/sound-design.md` §3).

2. Sourcing, per category (`templates/prompts/sourcing.md`)

Typical launch-film categories: `ui` (clicks, taps, toggles, pops), `keyboard`, `motion` (whooshes, risers), `impacts` (reveal hits, the logo), `ambience`, `music`; a character film adds `foley`, its worlds, its objects. Freesound (CC0 / CC BY; HQ preview `cdn.freesound.org/previews/<id//1000>/<id>_<user>-hq.ogg`), Mixkit (WAV `assets.mixkit.co/active_storage/sfx/<id>/<id>.wav`), composer libraries for music; licences read on each item's own page (`references/licences.md`); polite sequential downloads; every file measured:

{{PY}} -I <skill>/scripts/analyze.py audio/assets/ui/* --png out/audio-review/ui --out out/audio-review/ui.json
{{PY}} -m earshot realness audio/assets/ui/                  # gate: "real or pro-produced" (re-check trims: --start --end)
{{PY}} -m earshot rank "a single crisp trackpad click" audio/assets/ui/ --top 5
{{PY}} -m earshot match <file> "a soft cork pop" --alts "a gunshot" "a balloon burst"
{{PY}} -m earshot find <long take> "a single