Ears for coding agents: let AI hear, review and make sound. CPU-only, open source.
docs: sound for films (README, docs/SFX.md, cinetic uses earshot, skill Loop 5, CHANGELOG 0.3.0)
Leonxlnx60dce0fe92c0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 256823e..ab226af 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,46 @@# Changelog+## 0.3.0 - unreleased (0.3.0.dev0)++The sound engine of a film: the forge's delivered sounds as a bank, one-sound renders aimed at the picture, a+model-free audit, and film kits. Reference: [docs/SFX.md](docs/SFX.md).++### Added++- **The sound bank** (`earshot/forge/bank.py`, `earshot/forge/bank/*.json`, shipped as package data): the 183 forge+ v2 finals as their schema-2 render blocks at full precision (`forge_v2r6`), plus three tuned kalimba voices from the+ launch film (`pluck1`). Ids are `<category>/<member>`, `pluck/<name>` and `fit/<role>/<name>`; categories are the+ public names (no recipe module names needed). `python -m earshot.forge.bank build out/forge_v2/*/final -o ...`+ refuses any pick whose block does not re-render its WAV (183 of 183 within 1.2e-7); each entry stores its measured+ onset, peak, end, attack, centroid, loudness and a 50 ms envelope fingerprint, and `bank check` re-renders against+ it (length exact, peak within 5 ms, envelope within 0.5 dB). Rendering needs numpy / scipy only.+- **Knobs** (`earshot/forge/knobs.py`): `dur` (exact: the whoosh family scales its pass, length keys are searched by+ secant, then the file is faded or padded to the sample), `apex` (whoosh family: closed form, up to two measured+ corrections, then the peak is placed by trimming the quiet approach or padding silence: within 2.5 ms on every+ tested target), `pitch` (a note name or Hz into each recipe's own pitch parameter, co-scaling the parameters of the+ same body, inside the parameter's designed range; noise sounds refuse it with the reason), `weight` / `peak_db`.+- **`earshot sfx list / render / check`** and the audit (`earshot/forge/sfx.py`): polish's artifact detectors as+ warnings with context (gated categories may stop on their peak), a rising pitch-glide detector (a tonal sound+ climbing more than 4 semitones over 50 ms or more) and, for hits, a stacked-attack / pre-swell heuristic. Every bank+ render runs it.+- **`earshot kit init / render / check / audition`** (`earshot/forge/kit.py`): kit.json (schema 1) names one bank+ sound per role; `render` writes deterministic, cached takes and `kit.lock.json` with each take's measured onset /+ peak / end / loudness; a take that fails the audit is re-rolled on a new seed. Presets `calm`, `crisp`, `minimal`+ (`earshot/forge/kits/`) with a reason per role; riser, swell and suck off in all three.+- **`python -m earshot.forge.bank add-fit MODEL.json --id fit/<role>/<name> --source SOURCE.json`**: a fitted recipe+ as a bank entry with its source (CC0 / public domain unless `--allow-license`; NC / ND refused), rendered through+ `earshot.forge.fit`, tunable when the fit is tonal. Extra bank files load from `EARSHOT_BANK`.+- **Python API** `earshot.api.sfx_list / sfx_render / sfx_check / kit_init / kit_render / kit_check / kit_audition`;+ **MCP tools** `sfx_list`, `sfx_render`, `kit_render` (16 tools in all).+- Docs: `docs/SFX.md`; README "Sound for films"; `docs/INTEGRATION.md` "cinetic uses earshot"; the earshot skill's+ Loop 5 "make a film's sound kit".+- Tests: `tests/test_bank.py`, `tests/test_sfx_kit.py` (no models).++### Changed++- Wheels now ship the forge seed banks (`earshot/forge/seeds/*.json`) next to the bank and kit presets; before, a+ non-editable install had none.+## 0.2.1 - 2026-10-17Two fixes from a careful outside review (thanks, @markblundeberg).diff --git a/README.md b/README.mdindex 8114e1c..da51df0 100644--- a/README.md+++ b/README.md@@ -153,6 +153,38 @@ close, not identical: onsets, tone balance and noise texture still differ measuron the same 12 recordings; risers, zips and long designed sounds are untested. A fit is a derivative of its recording,so keep the source's licence with the recipe. Limits: [docs/FIT.md](docs/FIT.md#limits-honest).+## Sound for films: bank, sfx, kits++The forge's delivered sounds ship as a bank that renders by id, with no models and no network: 183 forge v2 finals+(34 categories) and three tuned kalimba voices, each stored as its render block and re-rendering its delivered WAV to+one 24-bit step. A film pipeline renders from it in seconds; searching new sounds stays an offline step.++```bash+earshot sfx list --kind whoosh # ids, lengths, peak times, cue kinds, knobs+earshot sfx render whoosh_fast/crisp -o w.wav --dur 0.8 --apex 0.32 # a new take aimed at a move (--seed N)+earshot sfx render pluck/kalimba -o e5.wav --pitch E5 # tuned through the recipe's own f0+earshot sfx check w.wav # clicks, cut tails, clipping, ring, rising glides+earshot kit init --preset calm -o audio/kit.json # calm | crisp | minimal+earshot kit render audio/kit.json --out audio/kit # takes + kit.lock.json (measured onset / peak / end)+```++- **Knobs** edit each recipe's own parameters, never resample: `dur` lands exactly, `apex` puts a whoosh's loudest+ moment within 5 ms of the target (measured within 2.5 ms), `pitch` takes a note name or Hz (pluck E5, a bell G5, a+ sub drop G1 measure 0 cents off); noise sounds refuse a pitch and say why.+- **The audit** (`earshot sfx check`, run on every render) is measurement only: clicks, cut tails, clipping, DC, comb+ ring, a re-rising tail, a tonal pitch that climbs more than 4 semitones (the rising "synth whip"), and for hits,+ stacked attacks or a build before the hit. 170 of the 186 sounds are clean; the presets use none of the others.+- **Kits** name one sound per role (tick, hit, whoosh.short, key, bell, text ...). `kit render` writes deterministic,+ cached takes and a lock with each take's measured sync points; a take that fails the audit is re-rolled on a new+ seed. The three presets sound every role but riser, swell and suck, use one clean hit for the lockup, and favour the+ families a blind listener took for recordings (taps, struck bells).+- **Python and MCP**: `from earshot.forge import bank; y, meta = bank.render('pro_sub_drop/ref', pitch='G1')`;+ `earshot.api.sfx_render / kit_render`; MCP tools `sfx_list`, `sfx_render`, `kit_render`.++Full reference (every knob, the audit, the kit and lock formats, the presets role by role, fit entries from+public-domain recordings, measured cost): [docs/SFX.md](docs/SFX.md). How cinetic uses it:+[docs/INTEGRATION.md](docs/INTEGRATION.md#cinetic-uses-earshot).+## Gallery`earshot gallery` turns forge outputs into one static HTML page for people with ears: no server, no network, no@@ -287,11 +319,12 @@ style of the 7 films behind it, not every good film. Details in [docs/LIMITS.md]earshot/ the package: CLI, Python API, MCP server, CPU model wrappersforge/ make sounds in code: DSP building blocks, critic, model-free tone checks, search, recipes/fit/ recording -> code: modal / sines / spectral fitters, quality metrics, recipe codegen+ bank/, kits/ the sound bank (render blocks + fingerprints, no audio) and the kit presets: earshot sfx / kitgallery.py the static listening pagedata/ vocabulary + calibration stats, realness model weights, launch profile (numbers only, no media)skills/earshot/ agent skill: how to listen with earshotskills/real-sound/ agent skill: real-recordings soundtracks (scripts, templates, prompts, references)-docs/ VALIDATION, LIMITS, FORGE_V2, FIT, the motion-SFX study, launch-video playbook, design notes+docs/ VALIDATION, LIMITS, FORGE_V2, FIT, SFX, the motion-SFX study, launch-video playbook, design noteseval/ evaluation scripts and results per area (see eval/README.md)tests/ pytest (fast by default; --slow loads the models)```diff --git a/docs/INTEGRATION.md b/docs/INTEGRATION.mdindex 6e1ed59..570322c 100644--- a/docs/INTEGRATION.md+++ b/docs/INTEGRATION.md@@ -1,10 +1,63 @@-# Integration: real-sound + earshot inside a Cinetic film (without changing Cinetic)--Cinetic (`~/.claude/skills/cinetic`) directs and renders launch films from code. Its Step 5 synthesizes the whole-soundtrack (`scripts/audio/score.py` + `synth.py`) from a beat-locked timeline. This document shows how a Cinetic film-gets a real-recordings soundtrack from `skills/real-sound` instead, and how earshot gives Cinetic's review loop ears,-using Cinetic exactly as it is today. The last section lists the small changes a future Cinetic could make so this-becomes one flag.+# Integration: earshot inside a Cinetic film++Cinetic (`~/.claude/skills/cinetic`) directs and renders launch films from code. Its Step 5 builds the soundtrack+(`scripts/audio/score.py`) from a beat-locked timeline. Two routes give that soundtrack better sounds: an **earshot+sound kit** (the first section: forge sounds rendered from earshot's bank, the route cinetic 1.1 takes by default when+earshot is installed), and a **real-recordings soundtrack** from `skills/real-sound` (sections 1-4, which use Cinetic+exactly as it was before 1.1). Either way earshot gives Cinetic's review loop ears (section 3).++## cinetic uses earshot++The effects of a cinetic film come from an earshot kit; cinetic keeps the conductor (timing, typing plan, levels,+ducks, arc, master, report, stems) and earshot supplies the voices. Rendering a kit is pure DSP: no models, no torch+import, seconds per film once cached.++```+src/sync.ts --export-cues--> out/cues.json ---------------------------------++audio/score.json "sfx": {"engine": "auto", "kit": "audio/kit.json"} ------+--> score.py --> master.py --> soundtrack.wav+audio/kit.json --scripts/audio/kit.py--> earshot kit render --> audio/kit/*.wav + kit.lock.json --^+```++1. **The kit.** `audio/kit.json` starts from a preset (`earshot kit init --preset calm|crisp|minimal`; calm is the+ default for text-led films) and is edited per film: the lockup hit tuned to the film's root (`edits.pitch`), another+ member for a role, a fitted sound. Roles are cinetic's cue kinds and their variants (below); `null` roles are not+ sounded.+2. **The bridge.** cinetic's `scripts/audio/kit.py` finds earshot (importable in cinetic's Python, `sfx.python` in+ `score.json`, `EARSHOT_PYTHON`, or `earshot` on PATH), runs `earshot kit render audio/kit.json --out audio/kit` in+ one process (cached: an unchanged kit re-renders nothing) and keeps the takes in `audio/kit/`, so the film rebuilds+ on a machine without earshot.+3. **Placement.** score.py plays one take per event (a new take per event by hash; typing cycles through the takes),+ placed by the sync point the lock measured for the role's `align`: the take's onset on the cue frame, a whoosh's+ loudest 5 ms on its apex, a riser's end on the hit. `level_db` and the event weight set its level; a cue whose role+ is `null` is skipped with a report line.+4. **Fallback.** earshot render -> the vendored `audio/kit/` takes -> cinetic's own synth voices with a loud warning.+ The build never fails only because earshot is missing.+5. **Listening.** `scripts/audio/listen.py` runs `earshot timeline --cues`, `sheet` and `critique` in one process and+ writes `out/qa/listen.json`.+6. **The lockup** is a stop-down and one clean element. `earshot kit check` warns when the hit role has two attacks or+ a build before the hit, and when any role's pitch climbs (the rising synth whip); score.py's stack guard warns on a+ second designed effect within 3 frames of the lockup or payoff.++| cinetic cue (kind, variant) | kit role | align |+|---|---|---|+| tick / tick crisp | `tick` / `tick.crisp` | onset |+| tock | `tock` | onset |+| hit | `hit` | onset |+| land / land light | `land` / `land.light` | onset |+| pop | `pop` | onset |+| whoosh (short / long move) | `whoosh.short` / `whoosh.long` | peak |+| suck, riser, swell | `suck`, `riser`, `swell` (off in every preset) | end |+| drop | `drop` | onset |+| key / key space / key return | `key` / `key.space` / `key.return` | onset |+| click / click confirm | `click` / `click.confirm` | onset |+| snap | `snap` | onset |+| bell (motif notes, progress steps) | `bell` (one take per pitch) | onset |+| a text fragment resolving | `text` | onset |++What earshot guarantees the bridge: the role vocabulary, kit and lock schema 1 (docs/SFX.md#kits), the CLI flags+above, deterministic takes, and a lock that names the bank version (a new bank version re-renders the kit, because+it is part of every take's cache key). The bank, knobs, audit and presets are documented in+[docs/SFX.md](SFX.md).## 1. What Cinetic produces that the soundtrack needsdiff --git a/docs/SFX.md b/docs/SFX.mdnew file mode 100644index 0000000..1c7ada0--- /dev/null+++ b/docs/SFX.md@@ -0,0 +1,308 @@+# Sound for films: the bank, `earshot sfx`, `earshot kit`++earshot 0.3.0 ships its forge sounds as a bank that renders by id, aims a take at the picture, audits it without+models, and renders a whole film's kit into takes with measured sync points. Everything here is pure DSP (numpy /+scipy): no models, no network, no recorded audio. It is the sound engine of a code-made film: a film pipeline renders+from the bank in seconds and only ever searches (`earshot forge`) offline.++```bash+earshot sfx list --kind whoosh # what is in the bank+earshot sfx render whoosh_fast/crisp -o w.wav --dur 0.8 --apex 0.32 # one take aimed at a move+earshot sfx render pluck/kalimba -o e5.wav --pitch E5 # a tuned note+earshot sfx check w.wav # the model-free audit of any sound effect+earshot kit init --preset calm -o audio/kit.json # a film's kit from a preset+earshot kit render audio/kit.json --out audio/kit # takes + audio/kit/kit.lock.json (cached)+earshot kit check audio/kit.json --out audio/kit # ids, knobs, the audit of every take+earshot kit audition audio/kit.json -o audition.wav # every take, role by role, at its level+```++Contents: [the bank](#the-bank) · [knobs](#knobs-dur-apex-pitch-level) · [the audit](#the-audit-sfx-check) ·+[kits](#kits) · [presets](#the-presets) · [Python, MCP](#python-and-mcp) · [fit entries](#fit-entries-from-public-domain-recordings) ·+[cost](#cost) · [limits](#limits)++## The bank++`earshot/forge/bank/*.json` (package data; the forge file is 275 KB, 64 KB gzipped): 186 sounds today.++| file | version | entries | what |+|---|---|---|---|+| `forge_v2.json` | `forge_v2r6` | 183 | every delivered forge v2 final (34 categories, 4-6 named members each) |+| `pluck.json` | `pluck1` | 3 | the tuned kalimba voices (`pluck/kalimba`, `pluck/kalimba_soft`, `pluck/kalimba_ring`) |+| `fit.json` (later) | `fit1` | - | recipes fitted from public-domain recordings (`fit/<role>/<name>`) |++`bank.VERSION` joins the file versions (`forge_v2r6+pluck1`); extra bank files load from `EARSHOT_BANK` (paths joined+by the OS path separator). Ids are `<category>/<member>`: the category is the public name (a user never needs the+recipe module behind it: `typing_key` renders with `recipes/keypress.py`, `pro_pop` with `pop.render_v2`,+`pro_typing_run` with `typing.render_run`).++**Faithful.** An entry is the final's schema-2 render block (`earshot.forge.schema`): recipe module, render function,+member, the complete parameters at full precision, seed, peak and palette gain. The build re-renders every pick and+compares it with its delivered WAV; one pick off by more than one 24-bit step (1e-6) and nothing is written:++```bash+python -m earshot.forge.bank build out/forge_v2/*/final -o earshot/forge/bank/forge_v2.json # 183 / 183 within 1.2e-7+python -m earshot.forge.bank build --pluck -o earshot/forge/bank/pluck.json+python -m earshot.forge.bank check [IDS ...] # re-render against the stored fingerprints+```++The forge's seed banks (`earshot/forge/seeds/`) are search starting points, not this: rounded parameters without+their render function; re-rendered from them, 34 of 94 checked finals come out as different sounds.++**Meta.** Each entry stores, measured on its render at -1 dBFS: `dur_s`, `onset_s` (the 1 ms envelope's first point+within 30 dB of its maximum), `peak_s` (the loudest 5 ms, 1 ms hop), `end_s` (the last 5 ms within 50 dB of the+loudest), `attack_ms`, `centroid_hz`, `lufs_m_max`, `channels` and a fingerprint (50 ms RMS frames in dB re the loudest,+to where the sound stays 60 dB down). A re-render on another machine is checked against it: length exact, peak within+5 ms, envelope within 0.5 dB (`bank.check`, `tests/test_bank.py`). On the build machine every entry re-renders+bit-exactly.++**Categories** (`earshot sfx list` has every member; `kinds` = the cue kinds / kit roles a category serves):++| category | kinds | for |+|---|---|---|+| click, pro_click | click, tick.crisp | cursor presses; bright designed UI ticks |+| hover_tick, pro_hover_tick | tick, tick.crisp | hover, rows passing, cursor blinks, counters |+| tap, pro_tap | tock, land.light, click, tick | taps and touches on a surface; the soft thump of a touch |+| toggle | snap, click | switches and lock-ins (press + latch) |+| pop, pro_pop, pro_pop_in | pop, land, snap | bubble pops; tonal pops; an element popping in (round low thump) |+| notify, pro_notify | bell, hit, text, click.confirm | struck bell chimes A4-E6; short clean dings a semitone apart |+| shimmer, pro_shimmer | shimmer | chimes ringing out, granular sparkle |+| whoosh_fast, whoosh_big, pro_whoosh_big | whoosh.short, whoosh.long, suck, swell | fast passes; big air transitions; the designed low sub swell |+| swish, swipe | whoosh.short | thin flicks and text slides; cloth and paper swipes |+| riser, pro_riser, downlifter | riser, drop | builds that stop on their loudest sample; energy falling away |+| pro_zip | zip | tonal sweeps across a cut (up / up_hi / arc rise in pitch) |+| impact, pro_impact | hit, land | a cinematic hit (3-6 s tails); a designed gated sub impact (0.7-1.3 s) |+| sub_drop, pro_sub_drop | drop | weight under a hit; the designed drop that blooms after the cut |+| logo_sting, pro_logo_sting | sting | composite logo reveals; launch gestures onto a tone |+| glitch, pro_glitch | glitch | glitch transitions; a designed stutter ending on the cut |+| typing_key, pro_typing_key, pro_typing_run | key, key.space, key.return, key.run | mechanical keys; designed key ticks; a whole run |+| pluck | bell, text, hit | a kalimba tine: tuned notes (native C5) |++## Knobs: dur, apex, pitch, level++`bank.render(id, seed=None, dur=None, apex=None, pitch=None, peak_db=-1.0, sr=48000, weight=None)`;+`earshot sfx render ID -o out.wav [--seed N] [--dur S] [--apex S] [--pitch NOTE|HZ] [--peak DB] [--weight W]`.+Knobs edit the recipe's own parameters (`earshot/forge/knobs.py`); nothing is resampled or time-stretched.+`meta['edits']` reports what each knob did and how close it landed.++- **seed**: `None` renders the delivered final (its own seed). Any other seed is a new take of the same member: the+ noise, jitter and micro-timing change, the character stays (the finals were picked on robust re-renders).+- **dur** (seconds, the file length): the whoosh family (whoosh_fast, whoosh_big, pro_whoosh_big, swish, swipe) scales+ rise, hold and fall together, so the pass keeps its shape; recipes with a length key (risers, downlifters, sub drops,+ shimmers, zips, glitches, typing runs, pro_logo_sting, the UI sounds' end gate) scale that key, render, measure and+ correct along a secant through the renders so far (at most 2 corrections, keeping the closest); the rest (impact,+ toggle, typing_key, logo_sting, pluck) keep their sound as it is. Then every dur lands exactly: a longer file is faded+ out to the length (raised cosine over a quarter of it, 10-150 ms), a shorter one padded with silence. A riser's+ length is exact by construction (`length` 1.0 -> a 1.000 s file that stops on its loudest 5 ms).+- **apex** (seconds to the loudest 5 ms, the whoosh family only): the pass engine's peak is analytic,+ `tp = rise * (|start_db| / 30) ** (1 / rise_k)`; rise is solved for the target, measured, corrected up to twice,+ then the closest render's peak is placed on the target by trimming the quiet approach (a head at least 20 dB under+ the peak, with a 3 ms fade-in) or padding silence before it. Measured: the closed form lands within about 12 ms on+ the fast family, but a broad fluttering pass's 5 ms peak moves non-monotonically with rise (whoosh_big and+ pro_whoosh_big swell: up to 50 ms for a 10 % change), so the search alone cannot promise 5 ms; with the placement+ every tested target lands within 2.5 ms (`edits['apex']`: `search_err_ms`, `fit`, `err_ms`, `ok`). Combine with dur+ for a move: `--dur 0.8 --apex 0.32` = a 0.8 s file whose loudest moment is 0.32 s in.+- **pitch** (`'C5'`, `'Eb6'`, `'F#4'`, `440`, `'440hz'`): the note goes into the recipe's pitch parameter and the+ parameters of the same body move by the same ratio:++ | category | parameter (co-scaled) | range |+ |---|---|---|+ | pluck | f0 | 130-2100 Hz |+ | notify / pro_notify | f0 (the head fundamental) | 220-3200 / 600-3200 Hz |+ | click, pro_click, toggle | pitch (the tink partials) | 1.2-9.5 kHz / 1.6-8 kHz |+ | hover_tick, pro_hover_tick | ping_f (tick_f), only members whose ping is on | 3-15 kHz |+ | tap, pro_tap, pro_pop_in | body_f (knock_f, glass_f) | 70-220 Hz |+ | pop / pro_pop | f0 (f_hi, f_lo, f_blip / + n_f0, n_f1) | 400-3500 / 280-1400 Hz |+ | sub_drop, pro_sub_drop | f1, the landing pitch (f0 keeps the glide ratio) | 28-62 Hz |+ | pro_zip | f1 (f0, fpk) | 80 Hz-12 kHz |+ | riser, pro_riser, downlifter | tf0, only members whose tonal layer is on | 60-4000 / 150-2500 Hz |+ | logo_sting / pro_logo_sting | root / g_root (root) | 300-2200 / 50-1800 Hz |+ | impact, pro_impact | body_f1 (body_f0, sub_f) | 34-75 Hz |+ | pro_whoosh_big | sub_f, only sub-led members | 25-120 Hz |+ | shimmer, pro_shimmer | key: the pitch class only (the register stays) | - |++ Noise sounds are refused with the reason (whoosh_fast, whoosh_big, swish, swipe, glitch, pro_glitch, typing_key,+ pro_typing_key, pro_typing_run), as are targets outside the range and members whose tonal layer is off. The render is+ measured: `edits['pitch']['measured_hz']` / `cents_off` (pluck E5, notify G5, pro_sub_drop G1: 0 cents; a tap's body+ is a damped thump, within about 60 cents).+- **level**: `peak_db` sets the sample peak (-1 dBFS by default); `weight` scales it by 6 dB per doubling (0.5 = 6 dB+ down) and refuses a level over 0 dBFS. Loudness inside a family was matched in the forge (`render_final()` keeps+ that palette gain); a kit's `level_db` carries the mix level per role.++## The audit: `sfx check`++`earshot sfx check FILE [--category C] [--role R]`, `sfx.check(y, category=, role=)`. Measurements only; every bank+render runs it (`meta['checks']`). Warnings make `ok` false; notes are information.++| code | what | from |+|---|---|---|+| clicks, edge | isolated discontinuities inside the sound; a first / last sample off zero | `polish.clicks` |+| clipping | flat tops at the peak, samples over full scale | `polish.clipping` |+| dc | an offset above -40 dB re peak | `polish.dc` |+| ring | a metallic comb in the tail (z > 15) | `polish.ring` |+| truncated | a tail cut while still decaying, above -45 dB; a note for the categories whose stop is the design (riser, pro_riser, pro_zip, glitch, pro_glitch, pro_impact) and for any sound that ends on its loudest moment | `polish.truncated` |+| silence | digital silence inside the sound (a note for glitches) | `polish.silence` |+| tail | the tail rises again by more than 6 dB (a note: a roll, a second event, a double member) | `polish.tail` |+| rising_glide | a tonal sound whose pitch climbs more than 4 semitones over at least 50 ms: the rising "synth whip" | `sfx.rising_glide` |+| stacked, pre_swell | for a hit (role hit / land): two separate attacks, or more than 100 ms of build before the hit | `sfx.layers` |++The glide detector tracks the strongest partial in 21 ms frames every 5 ms where it holds at least half of the frame's+80 Hz-10 kHz energy within +-3 semitones (a tone, also a fast smeared sweep; a noise band does not), splits the track+where it jumps more than 3 semitones, and reports the largest climb of its 5-frame median. On the 183 finals it flags+pro_zip up / up_hi / arc (+20 to +64 semitones), the zip and sweep leads of logo_sting zip_ping and pro_logo_sting+sweep_hit, and two bubble pops (pop/2, pro_pop/bloop: +6 semitones in 55-75 ms, a physical bubble); falling sweeps,+bells and plucks read 0. The layer heuristic reads a 25 ms RMS envelope (peaks within 6 dB of the loudest, 10 dB of+dip between them, in the first 0.5 s): two noise hits 60 or 120 ms apart read 2, a gated grain texture reads 1+(pro_impact short / air / swell: 1; deep: 2; rumble: 3); impact swell builds 220 ms before its hit.++Audit of the whole bank (each final at its own seed): 170 of 186 clean. Flagged: the three rising zips, the two+logo-sting leads, the two rising bubbles, typing_key light and laptop (comb ring), pro_hover_tick air and glass+(clicks), hover_tick detent and pro_typing_key soft (truncated), glitch dropout and logo_sting reverse_bloom, pro_shimmer+m3 (ring). The presets use none of them.++## Kits++A kit is a film's sounds by role. Roles are the shared vocabulary of a film's cue kinds and their variants:+`tick`, `tick.crisp`, `tock`, `hit`, `land`, `land.light`, `pop`, `whoosh.short`, `whoosh.long`, `suck`, `riser`,+`drop`, `key`, `key.space`, `key.return`, `click`, `click.confirm`, `snap`, `swell`, `bell`, `text` (a soft sound for a+text fragment resolving). Other role names are allowed; a renderer must know them.++`audio/kit.json` (schema 1):++```json+{"kit": 1, "name": "calm", "sr": 48000,+ "roles": {+ "hit": {"sound": "notify/m0", "takes": 2, "align": "onset", "level_db": -3.0, "note": "why"},+ "whoosh.short": {"sound": "swipe/velvet", "takes": 3, "edits": {"dur": 0.6, "apex": 0.2}, "align": "peak"},+ "bell": {"sound": "pluck/kalimba", "pitches": ["C5", "D5", "E5", "G5", "A5"]},+ "riser": null},+ "off": {"riser": "why this role is off"}}+```++| key | meaning |+|---|---|+| `sound` | a bank id |+| `takes` | takes per role (default 1, at most 32); take k renders on `seed + k - 1` |+| `seed` | default: the sound's own, so take 1 is the delivered final |+| `edits` | knobs for every take: `dur`, `apex`, `pitch`, `peak_db` (default -1), `weight` |+| `pitches` | one set of takes per note (or Hz) |+| `align` | the sync point a mixer puts on the cue: `onset`, `peak` (whoosh apexes), `end` (risers, swells); default per role |+| `max_s` | a take longer than this is faded out to it |+| `level_db` | the role's mix level relative to a take at its peak (for the mixer; the audition applies it) |+| `note` | why this sound |+| `null` | the role is not sounded: a renderer skips its cues |++`earshot kit render audio/kit.json --out audio/kit` writes 24-bit takes (`hit_1.wav`, `tick-crisp_2.wav`,+`bell_C5.wav`, `text_Cs5_2.wav`) and `kit.lock.json`:++```json+{"kit": 1, "earshot": "0.3.0", "bank": "forge_v2r6+pluck1", "sr": 48000, "name": "calm",+ "roles": {"hit": {"sound": "notify/m0", "align": "onset", "level_db": -3.0, "max_s": null,+ "takes": [{"file": "hit_1.wav", "seed": 1826701615, "pitch": null, "onset_s": 0.0, "peak_s": 0.0045,+ "end_s": 2.157, "dur_s": 2.3, "peak_db": -1.0, "lufs_m_max": -11.06, "sha1": "...", "key": "...",+ "checks": []}]},+ "riser": null}}+```++- **Deterministic.** The same kit renders the same takes. A take that fails the audit is rendered again on+ `seed + 1000 j` (up to 3 times) and the first clean one kept, as a sound designer discards a bad take; the lock then+ names `seed` and `planned_seed`. On the three presets 6 of 174 takes needed it (four key takes and a pitched ding+ that rang, a tap that stopped early); every preset take is clean.+- **Cached.** A take whose key (bank entry, seed, pitch, edits, max_s, sr, bank version, earshot version) and file+ hash match the existing lock is kept; changed roles re-render; files the new kit no longer names are removed (only+ files the old lock listed); `--force` renders everything.+- **Checked.** `earshot kit check` validates the file (ids, keys, knob names; close ids suggested) and audits every+ take with its role as context (a `hit` warns on stacked attacks and pre-swells). It notes restraint (riser / swell /+ suck sounded) and sounds the presets never use (rising zips, shepard risers and downlifters, logo-sting composites,+ shimmers, glitches, tonal pops), so the choice is visible.+- **Audition.** `earshot kit audition` writes every take role by role at its `level_db`, with an index `.txt`.++## The presets++`earshot kit init --preset calm|crisp|minimal` (`earshot/forge/kits/*.json`). All three sound every role except+`riser`, `swell` and `suck` (calm also keeps `drop` off): a reveal resolves on one element, and one clean hit carries+the lockup with nothing layered on it. Each role's `note` says why its member was chosen. The choices follow what+earshot measured and heard:++- In the author's blind test of the v2 finals (one listener, loudness-matched, randomised), the made clicks, pops,+ impacts, toggles, hover ticks, swipes, swishes and risers were picked out; taps, struck bells (notify) and shimmers+ were taken for recordings. So taps and bells carry the natural roles, and designed members appear where the idiom+ is designed (crisp UI ticks, the gated hit, minimal's sub-led set).+- Every member passes the audit; members the audit flags (ringing keys, clicking airy ticks, rising zips) are out.+- No pitch-rising zip or whip, no shepard riser or downlifter, no logo-sting composite, no shimmer, no glitch, no+ tonal pop with the 8-bit risk; the hit is one sound with one attack and no build.++| role | calm (text-led films, the default) | crisp (energetic product films) | minimal (designed, effects only) |+|---|---|---|---|+| tick / tick.crisp | tap/glass / pro_tap/glass | tap/glass / pro_click/tink | pro_hover_tick/soft / pro_hover_tick/ping |+| tock | tap/knuckle | tap/knuckle | pro_tap/soft |+| hit | notify/m0 (one struck C5 bell) | pro_impact/short (one gated hit) | pro_impact/air (one sub-led hit) |+| land / land.light | pro_pop_in/deep / tap/soft | pro_pop_in/deep / pro_tap/knock | pro_pop_in/deep / pro_tap/finger |+| pop | pro_pop_in/airy | pro_pop_in/round | pro_pop_in/round |+| whoosh.short / .long | swipe/velvet / whoosh_big/swell | whoosh_fast/tight / whoosh_big/swell | whoosh_fast/heavy / pro_whoosh_big/swell |+| drop | off | pro_sub_drop/quick | pro_sub_drop/ref |+| key / .space / .return | typing_key thock / deep / deep | typing_key crisp / thock / clicky | pro_typing_key glass / tick / double |+| click / click.confirm | tap/finger / pluck/kalimba_soft C6 | pro_click/mouse / pro_notify/ding_2045 | pro_click/soft / pro_notify/ding_1822 |+| snap | pro_pop_in/knock | toggle/latch | pro_pop_in/knock |+| bell | pluck/kalimba C D E G A (octave 5) | pluck/kalimba C D E G A | pro_notify/ding_1822 F G A C D (octaves 6-7) |+| text | pluck/kalimba_soft C5 E5 G5 | pro_tap/soft | pro_tap/finger |+| riser / swell / suck | off | off | off |++Set `edits.pitch` on `hit` (calm) and `drop` (crisp, minimal) to the film's root. A later bank version may swap in+fitted sounds (`fit/<role>/<name>`) where they beat a forge member; a kit references them like any other id.++## Python and MCP++```python+from earshot.forge import bank, kit, sfx, knobs+bank.VERSION; bank.list(category=None, kind=None); bank.get(id); bank.ids()+y, meta = bank.render('pro_sub_drop/ref', seed=3, pitch='G1') # float32 (n,) or (n, 2), meta (above)+sfx.check(y, role='hit'); sfx.rising_glide(y); sfx.layers(y)+kit.init('calm', 'audio/kit.json'); lock = kit.render('audio/kit.json', 'audio/kit'); kit.check(...); kit.audition(...)+from earshot import api # api.sfx_list / sfx_render / sfx_check / kit_init / kit_render / kit_check / kit_audition+```++MCP tools (`earshot mcp`): `sfx_list`, `sfx_render` (writes a WAV, returns the measured onset / peak / end and the+audit) and `kit_render` (a kit.json into takes + lock). They load no models.++## Fit entries (from public-domain recordings)++`earshot fit` turns a recording into a recipe; `add-fit` puts the fitted model into a bank file as+`fit/<role>/<name>` with its source:++```bash+earshot fit door_cc0.wav -o made/door_fit.py # writes made/door_fit.json (the model) next to it+python -m earshot.forge.bank add-fit made/door_fit.json --id fit/hit/door --source source.json [--vary 0.2]+# source.json: {"id": "freesound:123", "title": "...", "author": "...", "license": "CC0 1.0", "url": "..."}+```++The licence must be CC0 or public domain (`--allow-license` keeps an attribution licence; NC and ND licences are+always refused: a fit is a derivative and the bank ships inside an MIT package). The entry keeps the model (its fit+report dropped), seed, `vary` (take-to-take jitter), the source, the measured note of a tonal fit (`pitch_hz`, so the+pitch knob can tune it through the fit's own pitch / transpose / size knob, within an octave) and the usual meta.+Fit entries render through `earshot.forge.fit.render`. Default file: `earshot/forge/bank/fit.json`; `--bank` writes+elsewhere (load it with `EARSHOT_BANK`).++## Cost++Measured on the development laptop (AMD Ryzen 7 260, 2 threads, while other jobs kept the CPU near 100 %):++| step | time |+|---|---|+| `import earshot.forge.bank` + load the bank | ~3 s cold |+| first render in a fresh process | 10-45 s (numba compiles the filter kernels once per install, imports) |+| warm render + audit, median over the 186 finals | 0.5 s (UI sounds 0.05-0.3 s, whooshes 0.5-1.5 s, impacts and plucks 2-6 s) |+| `kit render`, whole preset, fresh process | calm 73 s (57 takes), crisp 61 s (59), minimal 25 s (58) |+| `kit render`, everything cached | 3-5 s (the process start; 0.1-0.6 s inside it) |++Render a film's sounds in one process and keep the takes: the lock and its cache are made for that.++## Limits++- The bank is the forge's sound, chosen and checked by measurement and one listener; it is not a library of+ recordings. A blind listener picked out several v2 categories (above); the presets lean on the ones that passed.+- Bit-exact re-renders hold on the machine that built the bank; another platform (numpy, scipy, numba versions) can+ differ by tiny amounts, which is why entries carry fingerprints with tolerances instead of hashes.+- Knobs leave the searched point: a far dur or pitch changes a sound's character, and only the model-free audit checks+ the edit. Ranges keep pitch inside each parameter's designed range.+- The whoosh engine picks its pan direction from the seed; a mixer mirrors a take for travel direction.+- No music and no ambience: the bank is effects and tuned notes.diff --git a/skills/earshot/SKILL.md b/skills/earshot/SKILL.mdindex 054d582..cbe5a0a 100644--- a/skills/earshot/SKILL.md+++ b/skills/earshot/SKILL.md@@ -27,7 +27,7 @@ Two ways in, same functions:llm tool; Claude Code fills it from the user's environment, other clients may need the key set in the environmentthat launches them: never write a literal key into a project file).Tools: measure, describe, match, rank, find, compare, ab, realness, timeline, sheet, critique, doctor,- llm_critique. Pass absolute paths; `full=true` returns all JSON. The server answers within a few seconds, longer on a cold or+ llm_critique; the sound bank (no models): sfx_list, sfx_render, kit_render (Loop 5). Pass absolute paths; `full=true` returns all JSON. The server answers within a few seconds, longer on a cold orbusy machine; if Claude Code shows no earshot tools, start it with `MCP_TIMEOUT=60000` (PowerShell:`$env:MCP_TIMEOUT=60000; claude`). `earshot mcp --warm` preloads the models at startup.If the machine is shared, set `EARSHOT_THREADS=2-3` (or `--threads 2` on any command). The first model call of a@@ -140,6 +140,27 @@ the pops band-unlimited with long hissy tails, while every model check called thmodel-free check, they now sit inside the real recordings' measured spread. The whoosh was re-made as a truly fastone. The impact (darker, swell-led) and the click (short tails) were not re-made. No human has listened yet.+## Loop 5: make a film's sound kit (earshot sfx / earshot kit)+Use this when a code-made film (a cinetic film, any cue sheet) needs its effects: render them from earshot's shipped+bank instead of writing synth voices. No models load; a whole kit renders in about a minute and re-renders in seconds.+1. Start from a preset: `earshot kit init --preset calm -o audio/kit.json` (calm for text-led films, crisp for+ energetic product films, minimal for designed effects-only films). Each role's `note` says why its sound was+ chosen; riser, swell and suck are off: a reveal resolves on one element, and the lockup is one clean hit.+2. Fit it to the film: `earshot sfx list --kind hit` (or `--category`) shows the candidates with lengths, peak times+ and knobs. Change a role's `sound`, set `edits` (`pitch` to the film's root for the hit or drop, `dur` / `apex` for+ a fixed move), `takes` (12 or more for typing, 2-4 elsewhere), `level_db`. Audition one candidate with+ `earshot sfx render ID -o x.wav [--pitch E5] [--dur 0.8 --apex 0.32]` and read its measured onset / peak / end.+3. Render: `earshot kit render audio/kit.json --out audio/kit`. The takes and `kit.lock.json` (measured onset, peak,+ end, loudness per take) are what the mixer places on cue frames: onset on the frame for hits and touches, the+ peak on a whoosh's apex, the end on a riser's hit.+4. Check: `earshot kit check audio/kit.json --out audio/kit`. Every warning names a take and a reason (clicks, a cut+ tail, comb ring, a pitch that climbs more than 4 semitones, a hit with two attacks or a build before it); swap the+ sound or the knob rather than keeping a warned take. Read the notes too (a sounded riser, a composite sting).+5. Listen through the finished film with Loop 2 (`timeline --cues`, `sheet`) and check that each cue landed.+Say plainly what the bank is: forge sounds made in code and checked by measurement and one blind listener, not+recordings. When the brief asks for recorded sound, use `skills/real-sound` instead. Fitted sounds (`fit/<role>/<name>`)+come from public-domain recordings and carry their source. Reference: `docs/SFX.md`.+## Optional: a second opinion in words (audio LLM)`earshot llm mix.wav --yes-upload [--with-timeline] [--prompt "Is the riser at 0:12 cheap?"]` asks Google Gemini fora rubric critique (sync, realism, mix, loudness, what sounds cheap, fixes with times). It only runs when the user has