SallyRS/real-sfx

---

name: real-sfx description: Sound design for motion videos with REAL recorded sounds from the user's own libraries (a sorted main pack of whooshes, hits, risers, pops, chimes, keystrokes, foley, ambiences plus fallback libraries) and UI cues from uisfx, never synthesized. Finds the moments from the project's own cue list or from the synthesizer script that makes its sound, from a HyperFrames composition, from a screen recording (regions: typing, toasts, scrolls, clicks) or from the picture itself, picks and processes the sounds, places them on the exact frame at the level the author's own sounds had, keeps the music and voice, takes a synthesized layer baked into the render OUT instead of doubling it, and returns a new MP4, a separate SFX WAV track, a cue report and a self-critique scoreboard. Use whenever the user asks to add sound effects or SFX, sound-design, "озвучь", "добавь звуки", "сфх", whoosh/hit/riser/click/typing sounds, UI sounds, to replace synthesized or generated sounds with real ones, or to make a motion graphic, promo, explainer, UI animation, screencast, HyperFrames render, After Effects or Premiere project sound better, or complains the sound is synthetic, generic or out of sync, even if they do not say "skill" or name a library.

real-sfx: real sounds for a motion video

The goal: the film sounds as if a person with a good library had cut it. So:

• Sound is never synthesized. Sources: the user's libraries (config.json) and uisfx (a ready CC0 pack of interface sounds, itself synthesized: the one exception, only for interface moments; "no synthesis" turns it off: --ui library). No fitting sound: the moment stays quiet and goes into the report. This overrides "no track: synthesize" from motion-standards.
• You cannot hear. Sound is read as numbers, words and pictures (references/listening.md). Do not present a pick as listened to: say what was checked by eye and by measurement, and what the user should listen to.
• Keep the music and voice when they carry the film. The result is always a new MP4 and a separate WAV track.
• Do not double. Synthesis baked into the render's audio is replaced by the real sounds, not layered under them (step 1). The critique measures this as a number (the doubling axis).
• Do not change the project or the skill folder. Put all working files in your own folder (work/, result/).

Inside Video Director

(Added in Video Director's copy; not in Clipwing's original. UPSTREAM.md lists every change.) This copy lives inside the Video Director skill and is run by its Sound stage: ../references/sound-stage.md, "Sound engineering". Those steps decide which moments get a sound, give this skill only those (build/audio/sfx/events.json), pin the recordings the user chose (sound_handoff.py pins), run it with --ui library, --no-loudnorm and no texture layer or bed, and take back only the effects track and the resolved cues (sound_handoff.py collect). Follow them, and read this file only for options they don't cover. Set REAL_SFX_CONFIG, REAL_SFX_INDEX, REAL_SFX_TASTE, REAL_SFX_RATINGS, REAL_SFX_STEADY and REAL_SFX_STYLES to paths under ~/.config/real-sfx/ (the plugin installs each version in a new folder, so anything written here is left behind on the next update), and don't use --remember, which writes into this folder (so does learn_style.py: copy a learned style into ~/.config/real-sfx/styles/).

Quick path

First python scripts/setup.py check (ffmpeg, main/extra libraries, index, uisfx) and python scripts/look.py FILM.mp4 --out work/look (frames with time + the original sound under them). Then, by what you have:

# 1. the project has an event list (docs/cues.json, scripts/cues.json) OR a script that synthesizes its sound (audio.cjs)
python scripts/from_cues.py PROJECT_FOLDER|docs/cues.json --video RENDER.mp4 --out work/cues.json
# 2. screen recording without a list: ui_events.py ... (references/screencast.md), then from_cues.py work/ui/events.json
# 3. picture only:                    find_moments.py FILM.mp4 --out work/moments; suggest_cues.py work/moments/moments.json --out work/cues.json
# 3b. SOFT COLOURED ANIMATION without a list (UI preview, illustration, motion graphics): automation sees 5-6 moves of 40.
#     step 2, "Silent animation without a list": find_moments.py FILM --out work/moments --fine; look.py FILM --at T --span 2.4
#     --step 0.1 --out work/at.png; YOUR OWN event list from the frames (references/typed-cues.md) -> from_cues.py - --ui library
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --plan     # what goes where; then without --plan
python scripts/critique.py result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav
python scripts/levels.py   result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav --json work/edits.json
# a film whose sound is ONLY SFX (no music or voice of its own): small sounds in the holes, then mix.py again (step 4, "Small-sound layer")
python scripts/texture.py work/cues.json --moments work/moments/moments.json
# the same film: a bed (one long dark real recording under the whole film; step 4, "Bed"), then mix.py again
python scripts/bed.py work/cues.json [--list]
# numbers against nine finished SFX reels (step 6, "Against the reference"): no scores, does not affect the verdict
python scripts/critique.py RESOLVED.json WAV --style clean-sfx-refs
# human ears made cheap (step 6): a page with the critique's questions and a one-tap verdict; the masking model
python scripts/listen_page.py build work/listen --moments result/film_sfx.mp4 --critique RESOLVED.json WAV
python scripts/listen_page.py serve work/listen [--lan]        # then: listen_page.py results work/listen --log
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --masking        # which sounds the rest hides (needs the venv)

A project folder finds its own event list (docs/, scripts/, assets/); the synthesizer script is read only when there is no list. Choose all from_cues.py flags before editing the sheet: running it again wipes manual edits (then sheet.py apply). Voice in the film: mix.py ... --voice-safe (depth normal; --voice-depth light when there are many quiet textures, deep only for rare sounds in pauses: it takes the interface out of the mix entirely). Music carries the film: --duck. Loudness: a rebuilt base matches the original by default; your own: --target-lufs NUMBER. No index, or the libraries moved: python scripts/build_index.py, then python scripts/listen.py tag-index. No uisfx: setup.py init --uisfx. Another machine: setup.py scan FOLDER, setup.py add-library NAME PATH [--tier main|extra] --index. Run scripts from the skill folder; quote paths with spaces or non-Latin characters; your own Python with non-Latin paths on Windows: PYTHONUTF8=1. In PowerShell, quotes break JSON arguments: put them in a file.

Where the sounds come from

What is needed	Where from
The base: whooshes, hits, risers, pops, chimes, keys, paper, foley, ambience	the main library (tier: main, path in config.json). A sorted pack with catalog.json / catalog.csv gives every sound its type and source recording, which beats guessing from file names
What the main library lacks: low drops, coins, short glitches	fallback libraries (tier: extra, marked ~ in results): only when the main library has fewer than three fitting sounds
Designed packs with their own roles	roles granular, atmosphere, power, music_transition, voice are never requested by auto-picking: take them explicitly (--role, "pick": {"role": ...})
An interface moment: click, tick, window, notification	uisfx (--ui auto) when the list itself names interface kinds (click, chime...): from_cues says why and where (routes: key -> library:click, pop -> uisfx:select)
Typing	always the library's real keyboard, even with --ui auto; a run of 8+ click events 35–170 ms apart is recognized as typing by from_cues itself (--no-typing-detect)
Physical contact: ball, step, bead, object	always the library: a ball on the floor is a dull thud, not select (recipe below)

No library yet: setup.py init --uisfx alone gives 78 CC0 UI cues. Free real-recording sources worth checking (read each licence): Freesound (CC0 filter), Sonniss GDC bundles, Mixkit, Pixabay sound effects.

"From my library", "no synthesis" or "sounds synthetic": --ui library. An accent on the logo or a "cha-ching" in a project with uisfx interface sounds: --from-library pop,bell (kind names from the list); for one sound: sheet.py set --at T --label bell id=65. Under tonal music:

• the pitch steps of uisfx repeats and of the library's tonal sounds (chime, pop, glass, coin) turn off by themselves when the project has a score (--ui-pitch off|cycle);
• the pitch of a real sound is tuned to the notes of the music: mix.py takes the sheet's music_ref (the bed without effects, the music stem) or --music-ref FILE and shifts a tonal sound by whole semitones up to 2 plus the cents that put it on a note (2.5 in total), if that puts it on a note; noise is left alone (--no-tonal-fit; scripts/tonal.py SOUND --music FILE --at T shows the notes);
• the intervals of the author's own frequencies (tick(t, 1800 * 2 ** (4 * i / 12))) become the pitch steps of the replacement (melody:).

Workflow

1. What is already in the sound

look.py shows the spectrogram of the native sound (voice is bands of phrases, music a carpet with a beat, silence is black); listen.py voice FILM.mp4 gives the share of speech and music. Three cases:

• The author's music or voice: they stay, SFX go on top (--duck / --voice-safe). Exception (a person's answer on a real film, 2026-10-19): the film was sent "to be sound-designed", its native sound is music only (listen.py voice: speech 0 %), and the person wants it without the music, like their own clean SFX reels. Make a version without music (from_cues.py ... --ui library --drop-original, then bed.py --id ... --level -46 with a favourite atmosphere), and a version with music if useful, and say which is which. In a blind choice of three (original / effects over music / effects only) the person chose the last one without a single complaint. from_cues prints BAKED: on such a film although there is no baked synthesis (speech 0 %, music 84 %, the attacks do not match the events: 7 % against 9 % by chance): this is a false alarm.
• Synthesis baked into the track (the project was written for a synthesized score): real sounds on top of it are doubling. from_cues.py checks this itself (BAKED:, unbake:) and removes the synthesis from the base without touching music and voice; how exactly, and what to do if the script fails or the synthesis sits inside the music stem (--extra-synth): references/project-audio.md (read it as soon as the output has BAKED, WARN stems, unbake: not possible, or the project synthesizes its sound with a script). After the build critique.py prints the doubling axis: the correlation of the layer with the original and with the new film (should be about 0).
• The sound of clips playing inside a screen recording's window: native, stays; events inside those windows are dropped.

2. Find the moments (from the best source to the worst)

• The project's event list or synthesizer script → from_cues.py (below). In detail: references/typed-cues.md.
• A screen recording → references/screencast.md (ui_events.py regions, matching keystrokes to characters, clip sound).
• HyperFrames with data-start and no list: from_hyperframes.py PROJECT --out work/moments.json. "1 moments" with 18 elements means the motion does not follow data-start: look for a synthesizer script.
• Video only: find_moments.py FILM --out work/moments [--roi x,y,w,h] [--from A --to B] [--fine]; kinds cut, burst, onset, settle (settle also fires on an empty frame or a loop at rest: look at the frame); look.py --moments ... draws the frames of the moments. Skeleton: suggest_cues.py (references/recipes.md); a draft is a start, not an answer. --fine for soft coloured animation (gradients, glows, pastel shapes that change colour rather than brightness): it also reads chroma changes, moments get src=chroma|luma; on three such films it finds 33–69 % of the events an agent wrote down from the frames (within 80 ms), against 13–25 % from brightness alone; 3–4 times more candidates (15–25 per 10 s). These are candidates: the frames decide.
• Under music: beats.py FILM --out work/beats.json --plot work/beats.png; with usable: true, mix.py --snap-beats (±50 ms). The grid is checked against the kick (the low band < 125 Hz separately): it prints how many beats landed on a kick within 40 ms. A grid next to the kick (the tracker sat on the hats, "0.22 s off") is moved onto it; a grid that lands on nothing gets usable: false, and --snap-beats ignores it. --plot draws the band, the kicks (green marks) and the grid (red lines): the marks sit on the lines, or do not trust the grid. If the music is yours and can be fitted to the picture: beats.py FILM --suggest-offset work/moments.json says how far to shift the music so cuts and hits land on beats (advice only; the music is not touched).

from_cues.py: python scripts/from_cues.py LIST|PROJECT_FOLDER|SCRIPT.cjs|- --video RENDER.mp4 --out work/cues.json (- reads the list from stdin; a BOM from PowerShell is understood). What it does and says by itself:

• is it the right render: the list misses the picture (VERDICT); a design-time list against a render timed to the voice: a time map from the project's anchors (timing.json with anchors or WARP, src/timing.js) or from the onsets of the synthesized stems, each event lands on its own onset (time map); --time-map FILE, --warp off|stems|audio;
• synthesis under the list: a whoosh lands on the peak of the synthesized sound, its length is measured from it (retime:); no move if the peak belongs to another sound (pop, bell) or the list time is already the centre of the whoosh: named with the reason; synthesis onsets with no event in the list are listed (--add-unlisted tick turns them into events);
• timbre: the brightness of the whooshes being replaced (centroid of the synthesized layer) feeds the pick (timbre:); --tone airy|dark sets it by hand;
• an unknown kind (bead, soft): it shows how the project defines it. Say it in one line, no file needed: --kind bead=click, --kind soft=pop, a role with limits --kind bead=role:click,max_dur=0.3,onsets_max=1, --kind bead=slices:740,763 (single sounds from these recordings; the quietest ones, 12 dB down, are not taken), --map '{"glass":{"ids":[65,54],"role":"chime"}}' (ids in turn; an element {"id":800,"slice":[0.78,0.12]}); --remember keeps it. Summary: declared N events: M voiced, K silent; the critique counts silent kinds as a hole;
• clusters: events of one kind closer than 25 ms are one sound (--fuse), runs faster than 14/s are thinned (--max-rate), the output says how many of each (thinned: key 23, tick 11);
• a typing stretch ({"t":19.99,"type":"typing","len":0.36,"n":99}) unfolds into keystrokes (--type-rate).

Silent animation without a list (UI preview, illustration, motion graphics; all four blind tests on 2026-10-15 were like this). Automation reads brightness and sees 5–6 moves of ~40 in soft coloured animation, and suggest_cues draws only whooshes from them: the draft here is a skeleton, not an answer. The path on which four agents out of four finished the film:

1. look.py FILM --out work/look, then find_moments.py FILM --out work/moments --fine.
2. Close-up frames in 2–3 s windows: look.py FILM --at T --span 2.4 --step 0.1 --out work/at.png (24 frames with time, 8 per row; --span 1 --step 0.125 for a fast stretch). Write down what moves and when: an element entering, a morph, a landing, a cursor press (visible by colour), digits counting, appearing and disappearing, a scene change.
3. Write the event list from the frames (format and kinds: references/typed-cues.md, section "No project list"): [{"t":0.80,"type":"pop"},{"t":2.19,"type":"key","len":1.4,"n":17},{"t":5.53,"type":"wipe"}], and from_cues.py - --video FILM --out work/cues.json --ui library --moments work/moments/moments.json (the list via stdin or a file). --ui library if the sound must not be synthesis: --ui auto sends click/chime/tick to uisfx.
4. Then the usual loop. sync on such a picture can be n/a: check with zoom.py and look.py --at by eye. After a dense list texture.py will usually add nothing: that is fine.

One physical object (a ball, steps, drops, knocks): --one-source thump,pop (any kind, including one named with --kind: ONE family of recordings is taken, takes in turn). thump and hit are taken from clean single hits of foley recordings (listen.py onsets ID shows them; bodies and scatters are cut into pieces), as one family; under music a hit gets a 150 Hz highpass (--thump-hp, --no-bank turns it off). Variety is not judged for such an object. A smaller hit's level goes up with pitch automatically. The decay of hits (a ball) follows the author's g; the levels of the pieces are matched by perceived loudness. What your library lacks (a rubber ball, rolling, plastic): do not invent it, leave it quiet. Motion across the picture: "pan": -1..1 in a cue (sheet.py set --at T pan=-0.6).

3. Editing the cue sheet without an editor

python scripts/sheet.py show SHEET (indexes are always in time order and work for any next edit); set --at 2.0 --label thump gain_db=-3 id=800 (a time alone names a layer; if there are two, add --label/--index; id=, file=, uisfx= replace pick), set ... --unset slice, drop, shift --by 0.12 --role whoosh, gain --db -3 (--role knows the role of a cue with id too), move, add SHEET '{...}' / add SHEET --from cues.json / add SHEET --event [email protected] --event [email protected]:0.8 (a moment by kind and time: routed like from_cues), top SHEET keep_audio=no 'base_audio=[{"file":"D:/p/music.wav","keep_level":true},{"file":"D:/p/vo.wav","key_only":true,"gain_db":1.1}]' (keep_level do not pull the base's loudness, key_only the stem only drives the ducking), in a batch: apply SHEET edits.json ([{"at":2.0,"label":"pop","set":{"gain_db":-6}}, {"label":"bead","drop":true}]), freeze SHEET RESOLVED.json (pins the chosen files: do it after the first round, otherwise picks drift).

4. Choosing sounds for the main moments: look, do not guess

python scripts/search.py --role hit --says "thunk|thump" --max-dur 1.3 --sheet work/hits.png --paths
python scripts/search.py --role whoosh --like 412 --target-dur 0.7 --sheet work/w.png
python scripts/search.py --query "lego|bodyfalls" --role foley        # substring of name and folder; a|b = either
python scripts/listen.py onsets 800                                   # single sounds of a recording and the CLEAN hits among them

PNG: the waveform and spectrogram of each candidate with its id (references/listening.md). Three kinds of search words: --query a substring of the name and folder (non-English too); --says plain words for the sound, YAMNet tags, English words for non-English names; --tag thunk,thump a model tag. Length in the results is audible: 0.36* means the file is longer and the rest is silence. --paths prints the path, tags and source recording. Write the chosen number as "id": 412. Choose by what moves and what it hits: paper is paper, a bead on a string is a plastic click. Library names lie: a pack's "Wrap Elements" is Crackle/Fire to YAMNet, "Game Select" is Pig/Oink, UI swipes are Camera/Ratchet. Before taking an id from a fallback library, look at its tags: search.py --paths.

Small-sound layer (texture.py): only for a film whose sound is one thing, SFX and nothing else. In nine finished SFX reels the pause between gestures is 0.5–1.2 s (median 0.7), the longest hole 1.4–5.8 s (median 2.5). Six films voiced by the skill, measured the same way, had pauses of 0.7–1.5 s and holes up to 1.3–6.5 s (four of them with music, which fills the holes there): small moves (a settle, a small appearance, a tremble) were left quiet on purpose, and in a film without music nothing but sound can fill them. texture.py SHEET --moments M.json voices such moves of the PICTURE that have no cue and lie in holes (longest hole first) with a short real drop or bubble from the main library (water, pop, otherwise click; at most 0.3 s; never synthesis), 2–6 dB under the role's level, and only up to the pace of the references, in gestures per 10 s (--target, default 9.0: the low edge of the middle of the nine references; no more than 4 sounds per 10 s). What it does NOT do: it never touches your cues (it only adds "texture": true; running it again replaces the layer, --remove removes it); it does not put a sound on a strong move or a cut without sound (that is a hole, it lists them: voice them for real); it does not work under the film's own music or voice (--even-with-audio overrides the refusal); it does not put a sound on a still picture. --dry only shows. Run mix.py again after it; the critique counts such sounds as half an event and does not judge variety or balance against the author by them, nor put them on the listen list. Listen to the film with the layer and without it (--remove): the script cannot hear whether the small stuff gets in the way. Running from_cues.py again wipes the layer: run texture.py after it.

Bed (bed.py): also only for a film whose sound is SFX and nothing else. In finished SFX reels the sound never drops out between events: the quietest tenth of the film sits on average 24 dB under the loudest 250 ms (median of nine; middle −26…−21), there is 0 % digital silence (250 ms windows quieter than −70 dBFS) in seven of nine (2 % and 15 % in two); films voiced by the skill had 4–67 %. A person hears a room, a hum, wind, a pad; a film with clean silence between sounds sounds bare. bed.py SHEET takes ONE long, dark (centroid up to 900 Hz), steady real recording from the library (role: ambience; voice, animals, songs, water, fire, steps are dropped by tags and by name; steadiness is measured: ripple, the spread of 50 ms levels over a second, at most 4 dB, and swing at most 12; --list shows the candidates with numbers, --id N or --query choose by hand) and lays it under the whole film in pieces with an even overlap (fade_curve: qsin, no loop seam; three DIFFERENT recordings in turn if the film is longer than one). The level is absolute: −54 dBFS (--level, the median of 250 ms windows in the finished master; mix.py renders the film without the bed itself and runs it through the limiter and the master, the bed: line in the output). This is a person's answer, not the references': three blind ladders of one recording at −56 / −50 / −44 / −36 dBFS, −56 chosen every time, −50 called "all good", −44 and louder "loud", the version without a bed called "empty" (so a bed is needed, but at the edge of hearing); the old rule of −24 dB under the loudest place of a dense film gave about −34 and was "the hum gets in the way". --floor DB is the old relative rule (that many dB under the loudest). The recording the person called an "all good" bed (wind, grass) passes the tag and brightness filters and wins the ranking. What it does NOT do: it never touches your cues (it adds "bed": true; running it again replaces it, --remove removes it); the critique does not count the bed as an event (no gesture, hook, variety or hierarchy), and verify.py and critique.py judge the sounds on the track without the bed (*_sfx_track_nobed.wav, written by mix.py): a bed fills any window, and a sound lost by the render would otherwise go unnoticed; under the film's own music or voice it refuses (--even-with-audio). The --style table shows its effect in the rows the quietest tenth under the loudest and digital silence. The bed does not touch the film's sounds: the track without it equals the render without a bed to the sample, including when matching the loudness of the replaced layer (measured without the bed). Running from_cues.py again wipes the bed: run bed.py after it. Listen to the film with the bed and without it (--remove): the script cannot hear whether the hum gets in the way or sounds like "noise". Human ears already corrected the choice once: on four films the "Ambient Noise" recording (clean lows up to 400–600 Hz, the level moving by 5–8 dB about twice a second) was called "the hum gets in the way" in three of four, while steady recordings measure 2–3 dB. So bed.py does not take moving recordings, and bed.py --scan measures the whole library once (cache ambience_steady.json; the picker reads it too for role: ambience, and a moving recording drops in rank). A bed is optional: if the person hears the film better without it, there is none (--remove).

5. Build

python scripts/mix.py cues.json --out result/film_sfx.mp4 [--plan] [--duck | --voice-safe [--voice-depth light|normal|deep]]
     [--base-audio FILE[:dB][@sec] ... [--duck-music]] [--drop-original] [--snap-beats] [--stems] [--export-clips DIR]
     [--target-lufs -14 | --no-loudnorm] [--sfx-trim-db X] [--no-match-layer] [--no-level-roles] [--ceiling-db -1]
     [--music-ref FILE ...] [--no-tonal-fit] [--no-mono-fix]

The cue sheet schema is in the header of mix.py: fit_dur, pitch, reverse, lowpass/highpass, pan, mono, layers, loop_to, anchor, slice ([start, length]; "first" the first SIGNIFICANT sound of the recording, "loudest" the loudest, {"onset": k}). A mouse click in a recording is two clicks: "slice": "first" keeps the press. A named id/file beats pick. A sound with a quiet lead-in (a breath, 85 ms of silence before a pop) is placed by its audible start. The moment of a sound (round 9, the sync test). For roles placed by their peak (hit, whoosh, riser, chime, error, glitch, foley, paper ...), mix.py chooses the point from the sound itself: a sound that gets loud fast (a hit with a body, a beep, a texture) is placed by its arrival (anchor: arrive: the first 60 ms within 6 dB of the loudest), a sound that builds to a climax (a riser, a swell, a lift before a drop) by its peak. The loudest 20 ms of a noisy sound lie somewhere inside it, and placed by the peak such a sound came 0.15–3 s before the picture (in round 8 the mark "missed the picture": 46 % against 9 %). Arrival is used when the sound gains strength (from −20 to −3 dB) faster than 0.45 s and arrives at least 0.10 s before the peak; otherwise the peak. In the blind test of round 9 (17 cards, 10 decided) arrival won 5 cards with sounds that gain strength fast, the peak won 5 (4 control risers and lifts, and a paper crunch), "start" won none. An explicit "anchor": "peak" or "arrive" is taken as is (arrive skips both thresholds); verify.py judges a sound with arrival by its arrival. Mono. A stereo sound with its channels in antiphase (about 2 % of a typical library) sums to zero in mono: on a phone speaker, in one earbud, in a platform's mono mix it is gone. mix.py plays such a sound from its single louder channel on both sides (mono: in the output; --no-mono-fix keeps it as recorded, "mono": false on a cue keeps one sound, "mono": true|"left"|"right" does it by hand) and measures it by that channel (by the sum it is "silence").

Levels.

1. A role is brought to its peak (hit −4, whoosh −9, riser −12, click/ui/pop −14, ambience −24 dBFS); gain_db is the deviation from the target. Equal peak is not equal loudness: a thin bright whoosh at the same peak is 15 dB quieter than a dark one. Within a role, sounds are brought to one perceived loudness (the median, at most ±6 dB, peak no higher than −1.5 dBFS) BEFORE the author's gain_db (level: in the output; --no-level-roles; loud_after_db, level_adj_db in resolved).
2. If from_cues knows the loudness of the replaced layer, the whole SFX layer is pulled up to it (SFX layer: ... -> +N dB; only upward). The pull absorbs a global raise: sheet.py gain on all cues changes nothing in the end. Louder than the replaced layer: --no-match-layer and gain; one quiet moment: gain on it alone.
3. Event balance against the author's layer: levels.py RESOLVED WAV --json work/edits.json reads the momentary loudness (BS.1770, 400 ms) of the new and the replaced layer around each event and writes a batch for sheet.py apply: typing, ticks and bells land where the author's sound was. The critique calls the same the match axis. Warnings: capped (a quiet recording), a slice raised by more than 12 dB, a cue peaks above 0 dBFS before the limiter.

What is not obvious about levels (it came up for all four agents in the blind test):

• gain_db is a deviation from the role level, and the roles are already quiet (pop and click −14, chime −13 dBFS peak): small stuff is 0…−4, not −7 (that is a −21 peak). What will really land is shown by mix.py --plan (the gain column) and peak_after_db.
• The leveller trap. A thin bright sound is raised to the role's perceived loudness (up to +6 dB), its peak becomes the highest in the film, the master gain drops, and the whole film loses 2–3 LU although no other sound was touched. The cure is to lower THAT sound (peak_after_db in resolved, --plan), not to raise the others; --no-level-roles turns the levelling off. sheet.py freeze pins files and layers, but not these level corrections.
• Lowering a sound that hits the peak ceiling gives half as much: the normalizer brings it back towards the role median. Measure the result by peak_after_db, not by the gain_db you wrote.
• The ceiling after AAC. Default −1.0 dB; the encoded file can be 0.1–0.2 dB higher, and in a film with short sharp sounds the codec sometimes throws ONE frame 2–4 dB above its input (the limiter before it cannot see this). mix.py re-measures the file and fixes such a place locally: a dip of ~0.1 s by exactly as much as the frame overshot (output AAC overshoot: N place(s) ... dipped locally); the whole ceiling is lowered only when the overshoot is everywhere. The whole ceiling used to be lowered, and the film lost up to 0.8 LU. --ceiling-db -1.5 still works.
• A cue's label stays from its kind ("whoosh x0.25") after the sound is replaced by id: sheet.py set --at T label=..., otherwise the reports lie. A typing piece has the role click, like a mouse: sheet.py gain --role click moves both keys and clicks; separate them with --label key.
• A thin sound and its loudness. A shimmer peaking at −6 dBFS at −47 LUFS is common: such layers hold the limiter and the master gain and are barely heard. Lower the peak, raise the density.

Loudness. With no native sound the result is pulled to −14 LUFS. With the film's own sound the author's balance is not touched; a base rebuilt without synthesis (script, stems) is pulled to the original's loudness by default and takes its peak ceiling. A sparse film cannot be raised to −14: the loudest peak sets the loudness; the honest move is to accept the measured value (−15..−16), raise the quietest events or lengthen the tails. Sub drops add 2–3 LU that a phone speaker does not have: read the loudness without the lows too (highpass 150). *_sfx_track_in_mix_level.wav is the SFX at the MP4's level.

Under a voice. --voice-safe ducks the SFX by the voice stem (voice_stems in resolved), otherwise by the whole base. Console: how many dB the ducked track is quieter than the dry one in power. normal ≈ −9 dB on the sounds, light ≈ −4, deep down to −24: quiet typing and ticks under deep and in a film with speech 75 % of the time vanish from the mix (the critique calls this audibility). Move the sounds into pauses or keep light/normal.

6. The self-critique loop (required before showing the result)

python scripts/verify.py   RESOLVED.json WAV [--all]
python scripts/review.py   RESOLVED.json WAV --out result/review.png [--chunk 30]
python scripts/critique.py RESOLVED.json WAV [--moments M.json] [--list] [--style clean-sfx-refs] --rounds N --out result/critique.md
python scripts/levels.py   RESOLVED.json WAV --json work/edits.json        # against the author's layer, if known

1. verify.py: every sound is on the track in its place (MISSING: the render lost it, rebuild); a click is judged by its first burst, the layers of one moment together; for a short loop it prints loop seam (the seam is quiet); the mono: line says how many dB the track loses in mono (0 = channels equal, 3 = unrelated, 6+ = something cancels) and which sounds. critique.py: scores 1–10 for hook, sync, coverage, pacing, variety (by source recordings; a run of 5+ identical ones is a "machine gun", except clock ticks), hierarchy (by perceived loudness), peak headroom, loudness, balance, doubling (the synthesis is gone), match (events against the author's balance), audibility (after ducking the sound is still heard), mono (the mix summed to mono: a sound that cancels is named with a timecode and sheet.py set ... mono=true), and under a voice by speech and lows, plus the three worst with timecodes (--list prints every speech moment with the reduction it needs). n/a does not mean "passed". Thresholds: balance is good when an event's median is −12…+2 dB to the sound around it (large ones −8…+5); match ±3 dB; audibility: the sound's peak no lower than −30 dB to the film's sound around it (if the author had it that quiet too and match is fine, that is a note, not a fail); mono: a sound losing more than 6 dB in the sum is a fail, the track as a whole up to 3.5 dB is normal (a wide stereo recording). The listen list: at the end it prints up to five moments where the numbers are least sure (the hook, the loudest, misses in sync, balance, speech, mono, sounds that were pulled up or retuned; different kinds of risk, not one), with a question for the ear; --listen-out FILE.wav cuts them (3 s of the film's own sound each) into one file. The script cannot hear: this is what a person should listen to in headphones and once on a phone speaker. Do not say "sounds good" without it. The only ears there are belong to a person; make them cheap. listen_page.py build FOLDER --moments FILM.mp4 --critique RESOLVED WAV cuts the list's moments into 3-second pieces and builds a page: the critique's question under each, a one-tap verdict (ok / loud / buried / harsh / extra / missing) and a note; --ab LABEL v1.mp4 v2.mp4 [v3] puts versions of one film under 1 and 2 in random order (bed or not, two bed levels, original or the skill), switching on the fly; a pair can have its own question ("label ## question"), its own version names (--labels can repeat: the set matching the number of versions is used), pieces shorter than 8 s loop, up to nine versions. listen_page.py serve FOLDER [--lan] (with --lan the page also opens on a phone on the same network: that one time on a speaker); answers are written to verdicts.json on every tap; results FOLDER [--log] unblinds them (what won, which marks a version got) and with --log appends them to the skill's listening_log.json: data to check the numbers against (the masking model below, the thresholds). Do not fit the answers to the numbers: the page shows the question, not a number. Taste by category (taste_test.py): which sound is good for a click, a transition or a hit is decided by one person, and the library holds hundreds of sounds per role. The test takes one and the same picture from the person's films (a button, a wipe, a cut to a title, a notification; hosts.json names the moment) and puts ten different sounds of one role on it: the three the picker would take first (so the skill's default is tested too) and the seven most unlike each other in brightness, attack, length and weight. Each category has a repeat of one sound and one sound of another role (controls: does one ear say the same thing twice, does the picture decide; marked in the results, the person is told). A clip is the sound where mix.py would put it (role level, no normalization). Verdicts: love / ok / not here (a good sound, but not for this picture: mark what it is better for) / never; reasons and "better for" as chips. taste_test.py plan OUT --hosts hosts.json, render OUT, page OUT, then listen_page.py serve OUT/page; results OUT prints by category the verdicts, the agreement of the repeat, what the picture said about the other role, how the loved differ from the rejected (median brightness, attack, length) and how the picker's first three were rated; --apply puts "love" into taste.json love (the picker prefers them), "never" into ban (never taken), "not here" into not_for (ranked 1.2 lower in that role, not a ban), "better for" into better_for, the rest into notes. Ratings accumulate in taste_ratings.json (a personal file, not packaged; one entry per role and sound: one file can sit in several roles); taste_test.py round OUT --hosts H.json --roles ... makes the next round in one command (rated sounds are not taken; render --only ROLE rebuilds one section). The ambience section is the bed: a recording is laid under the picture with three identical "loved" sounds on top (accompany in hosts.json), and the person judges the background; the controls there are a repeat and a "known" bad hum. plan --reuse N puts N already rated sounds (best and worst) into a new picture: does the verdict belong to the sound or to the picture; ladder OUT --hosts H --sounds ... lays one background recording at several levels and without it (blind, 1 / 2 / 3 ...): the answer is a level, not a recording. An answer with chips only and no verdict is still an answer (the reasons are counted). Interface sounds: library or pack. A host with "kind": "uisfx" puts one cue (press, select, success) in all 12 uisfx packs next to two loved library sounds on one picture. taste.json gets uisfx ({cue: {pack: verdict}}; "synthetic" without a verdict counts against the pack) and ui_source ({cue: "library" | "uisfx"}, when the means differ by 0.5 or more). from_cues.py then takes a library sound for that cue (an explicit --ui uisfx still forces the pack), and when it takes a pack, the best by taste (taste_pack; a tie keeps the default); notification takes the verdict of success until it is tested separately. In the author's first test (2026-10-15) the library won press and success (clicks 2 of 2 "love" against 1 of 12 packs, "synthetic" on 11 of 15), while for select the packs held (9 of 14 "love"). Taste is not predicted from measured features or embeddings (checked on the answers: within a role the correlation is 0.1–0.2), so the lists are explicit, and sounds nobody has heard yet are judged by a person, not a model. Until the person has answered, there is no taste: do not make it up from file names. Tuning by ear and choosing a sound for a moment (rounds 5 and 6, adjust_test.py, moment_test.py): two tests of another kind, on a piece of a real film with its music and voice. adjust_test.py gives the person a level slider for the new layer and accent variants, blind, with marks along the way ("loud", "harsh", "extra", "missing"). moment_test.py puts ONE sound from the candidates on a moment of the film, blind and at one loudness (the film's current sound, the best by taste, ones far from them, ones named by hand, silence): the person says which sound belongs to the moment. listen_page.py builds the pages (kinds adjust and moment); details at the top of each script; they are not in the selftest (run by hand). The masking model (mix.py --masking, needs the venv: listen.py install --yes; or maskmodel.py RESOLVED CLIPS after --export-clips): each cue is a target, everything else at that moment (other cues, the bed, the native music and voice) is a masker, over 24 Bark critical bands, with masking spreading to neighbouring bands, forward masking and the absolute threshold of hearing; a sound is heard where its power over 192 ms stands above the threshold. It prints how many sounds are clear (10 dB or more above the threshold), fine (3–10), borderline (0–3), masked; how many dB of headroom the bed takes from the sounds and which sounds would be heard without it; the five least audible, with the band and what covers them (bed / other cues / native sound). Masked sounds go on the listen list with the question "is this heard at all". Layers, texture and background (ambience, vehicle) are not judged: they are meant to sit under the rest. This is a textbook model of tones and noise applied to transients: it puts the places in order, the ear checks the first ones; --offset-db tunes it to your verdicts from the page. A model that describes sound in words (hear.py, optional, about 3.1 GB: hear.py install --yes): MiDashengLM-0.6B on the CPU, offline, revision and code checked. hear.py bench on sounds with a known answer showed that it is no ear for this skill's questions: "is there a hum under the sounds" gets "yes" to everything (6 of 12 = chance), "how many clicks" gets "1" (0 of 6), "which is louder" gets "the first" (3 of 6); what the sound is (category): 12 of 27, good for hits, glass and typing, bad for whooshes, paper and ambience. So it is NOT built into the critique: what it cannot do is measured (the critique, the masking model); hear.py describe FILE [--span T0 T1] [--ask ...] stays a rough second opinion on WHAT the sound is. Against the reference (--style clean-sfx-refs, or your own style from learn_style.py): at the end, a table "this film | median of the references (middle half) [range] | inside / low / high / BELOW / ABOVE". No scores, it does not affect the verdict or the exit code. The SFX layer is measured by the same code as the references: gestures per 10 s, the pause between gestures (median, P90, longest), the spread of gesture levels, the typical gesture against the loudest, the first sound, the share of gestures with lows, the 30–100 Hz bed, the quietest tenth under the loudest (floor), digital silence, loudness. Under every step outside the middle, a line on what usually moves the number (texture.py, bed.py, hierarchy, hook). Read it honestly: the references are SFX reels where the sound is the content; a film with its own music and voice should not look like them (the table says so itself), and "BELOW" on the bed means only "there is no such bed", not "bad". Your own references: learn_style.py refs.txt --name mine; a line film.mp4 | | x0,y0,x1,y1 limits the picture to a region (an AE timeline under the animation is not motion). How the critique counts pacing (this was missing from the text and threw agents off): events are taken by cue; a run of one role with pauses up to 0.25 s (0.7 s for typing) is one event, layers within 80 ms are attached to their moment (the first key of typing is not attached to another sound), click, ui, data, sounds shorter than 0.15 s and the texture.py layer weigh half, layers are not counted. The norm is 3–9 weighted events per 10 s, a 1.2 penalty for each above 9 (0.4 for a project list). For density there is one definition: gestures per 10 s, a gesture being sounds without a 0.25 s pause between them (layers and keys count, common.gesture_times). This is what the --style table, the texture.py target and "too many" for a film WITHOUT its own sound use: by the nine references (6.9–15.1, median 11.4) "too many" starts above 1.1 × 15.1 ≈ 16.6 gestures per 10 s, not above 9 weighted events; a film with its own music and voice keeps 3–9. Intervals where moments are not judged (still frames, a clip with its own sound): the sheet key quiet, sheet.py top quiet='[[8.4,10.7]]'. --append appends the round to --out: the history of the loop in one file.
2. review.png as a strict sound designer; fast places up close: zoom.py RESOLVED WAV --at 12.4 --span 3 [--video FILM] (--out defaults to next to the sheet); under a voice masking.py RESOLVED WAV [--lowend] (takes *_sfx_ducked.wav from the sheet itself; without that file it judges the dry track and warns that masking is overstated), speech_map.py FILM --cues RESOLVED (a map by the sheet's voice stem, not by the music under it).
3. Fix the three worst (sheet.py), rebuild, repeat. A new film gets at least 3 rounds, all axes 8+. Tell the user the scores and what was fixed. Typical: speech is buried → shorter sound, quieter by the amount stated, into a pause; lows → highpass ≥140 Hz; low balance → gain on the events and --no-match-layer, not --sfx-trim-db.
4. An axis falls short because of the metric, not the sound: explain it with timecodes, do not cure it by inserting a sound. This happens with: a recording under clips with their own sound; a short 4–5 s loop; still frames; waiting for a model's answer and reading (silence is right); a sparse film (loudness, balance); one physical object; density set by the author; a film where the voice runs 80 % of the time (balance is judged by events outside speech); a word starting under a sound (the attack frame), a breath in a phrase pause; a screen recording (pacing is the person's pace: pacing is n/a for it).

7. Deliver

The path to the MP4, the separate WAV (stems and clips if made), how many sounds from which libraries (the report names library, main pack N / fallback M / uisfx K), what was left quiet and why, the final loudness, the five moments of the listen list (with timecodes and a question for the ear; critique.py --listen-out). Ask the user to name sounds they did not like: taste.py ban ID --why "..." / love ID. Handoff to HyperFrames / After Effects / Premiere: references/handoff.md (ask before calling other skills). Round renders (rounds/, _work/) weigh hundreds of MB: offer to delete them.

Taste rules

• Hook: a sound in the first 2 s (music or voice is a hook too; if the picture's first event is later, the sound on it is the hook), then something new every 2–4 s; emptiness longer than 4–5 s without a reason (a still frame, native sound) is a hole.
• One big moment is layers (hit + pop + dust), not one loud file; at most 3. Layers within 80 ms count as one event for pacing; in layers they stay one moment for sync too.
• Not a hit on every cut (heavy ones at most a third); repeats of one file give the pack away; four takes of one recording are one sound.
• Auto-pick name filters (mouth pops; drum fills in ui / pop / click / chime; censor beeps in error; stretching, rubbing and belt creaks in cartoon) are lifted by a word in the query (--query, says, like) and by the person's love: a sound in love always passes them. A ban and a love apply to every copy of a recording (one recording can sit in the library twice).
• The interface language is one: buttons sound like one family. Typing: animated 8–14 keystrokes a second, live typing one sound per keystroke, one keyboard for the whole text.
• Under a voice, SFX 6–10 dB quieter without beds, but audible; under music do not add your own pulse, put what matters on the beat, tonal sounds on the note.
• A role label drives the pacing score (click, ui, data weigh half): a run of light texture goes in as click, but do not hide real accents behind the label. The texture.py layer weighs the same ("texture": true).
• A film whose sound is only SFX is denser than one with music: by the nine references 6.9–15.1 gestures per 10 s (median 11.4, median pause between gestures 0.7 s), the longest hole a median of 2.5 s (critique.py --style). This is an example, not a law: a calm picture has its own silence.

What is where

• scripts/: setup, build_index, look, find_moments, ui_events, from_cues, from_synth, unbake, from_hyperframes, beats, suggest_cues, texture, bed, search, contact_sheet, sheet, mix, levels, tonal, listen_page, taste_test, adjust_test, moment_test, maskmodel, hear (the optional describing model), verify, review, zoom, masking, speech_map, critique, refstyle, taste, learn_style, listen, package.
• references/, as needed: project-audio.md (synthesis in the render's sound, stems, a synthesizer script, the author's chain); typed-cues.md (the list format, kinds, time map); screencast.md (screen recordings); event-map.md, recipes.md (which sound for which event); listening.md (tags, spectrograms); handoff.md (handoff to other programs); profiles/clean-sfx-refs.json (the numbers of nine reference SFX reels for critique.py --style).
• tests/selftest.py: a selftest on synthetic material (189 checks, 188 without the skill's venv, ~5 min); run it after editing scripts, 3 times in a row.
• tests/resound.py (+ tests/resound.md): the blind "resound" test. Finished films with good sound (a list, as for learn_style.py) are cut down to one animation and stripped of all sound, a fresh agent voices each from SKILL.md alone, then both sounds are measured by one code and compared in numbers (density, pauses, first sound, lows, silence, timing agreement against chance) and with an A/B pair to listen to. Run it when you change what decides WHICH sound lands (choice, density, bed, critique), not only that nothing breaks. Steps: prepare, snapshot, prompt (the text for the agent), agents, eval, check; details in tests/resound.md.