Skip to content

Ears for coding agents: let AI hear, review and make sound. CPU-only, open source.

docs: fitted sounds in the bank, presets by measurement, adding your own fit, fit takes

Leonxlnx41836349fcfc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ab226af..d0fce3f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,14 +32,35 @@ model-free audit, and film kits. Reference: [docs/SFX.md](docs/SFX.md).
`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).
+- **Fitted sounds in the bank** (`earshot/forge/bank/fit.json`, `fit1`; `bank.VERSION` is now
+ `forge_v2r6+fit1+pluck1`): 15 recipes fitted from CC0 recordings on Freesound, `fit/<role>/<name>`, each with its
+ source (title, author, URL, licence) and the take-to-take `vary` at which its takes passed the take check (seeds
+ 0-4 as the bank renders them: no hard artifact beyond the recording's, every audit warning also on the recording,
+ CLAP >= 0.90 to the fit's own render and within 0.06 of the fit's CLAP to the recording, excess energy within
+ 1.5 dB, loudness spread <= 2 LU), at a fit grade of high. Credits: `docs/CREDITS_FIT.md` (CC0 needs none).
+- **Fit takes** (`earshot/forge/fit`, details in [docs/FIT.md](docs/FIT.md#takes-a-fit-rendered-for-use-03)):
+ `fit.render(model, seed, vary=v)` with `vary > 0`, or `take=True`, renders a take. Modal modes and sines partials
+ ring out past the trimmed recording's end instead of stopping on a ringing tail (13 of 46 CC0 fits had cut tails in
+ their takes), takes are high-passed at 8 Hz (no random DC offset), a spectral model's takes keep one loudness
+ (a cloth whoosh's 8 seeds: 7.3 -> 0.45 LU apart), and a sines residual follows the recording's roll-off above 16 kHz
+ (`residual.hf`; no more noise above 20 kHz the recording lacked). `earshot fit --takes` scores candidates on seeds
+ 0, 1, 2. The fit itself is unchanged: on the 12 validation refs every seed-0 and seed-averaged quality number is
+ the same as in 0.2.
+- `earshot doctor` reports the sound bank: its version, the files it loaded and how many sounds of each type.
- 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).
+ Loop 5 "make a film's sound kit"; `docs/FIT.md` "Takes"; `docs/CREDITS_FIT.md`.
+- Tests: `tests/test_bank.py`, `tests/test_sfx_kit.py`, `tests/test_fit_takes.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.
+- **Presets use the fitted sounds where the measured comparison favours them** (earshot match of the role's
+ description, also against synth-blip descriptions, and earshot realness): calm tick, pop, short whoosh, space bar,
+ click and snap; crisp tick, light touch, text, click, snap, key and space bar; minimal light touch, text and snap
+ (16 role changes). A changed role keeps its loudness (`level_db` moved by the measured difference at the same
+ peak). Every note now says what the sound is and what was measured; no note cites a listening test. All takes of
+ the three presets pass `earshot kit check` (57, 59 and 58 takes).
## 0.2.1 - 2026-10-17
diff --git a/README.md b/README.md
index da51df0..927c8dd 100644
--- a/README.md
+++ b/README.md
@@ -156,8 +156,10 @@ so keep the source's licence with the recipe. Limits: [docs/FIT.md](docs/FIT.md#
## 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.
+(34 categories), each stored as its render block and re-rendering its delivered WAV to one 24-bit step, three tuned
+kalimba voices, and 15 sounds fitted from CC0 recordings (clicks, a tick, pops, touches, keys, a snap, a bell, a
+whoosh; credits in [docs/CREDITS_FIT.md](docs/CREDITS_FIT.md)). A film pipeline renders from it in seconds; searching
+and fitting new sounds stay offline steps.
```bash
earshot sfx list --kind whoosh # ids, lengths, peak times, cue kinds, knobs
@@ -173,11 +175,12 @@ earshot kit render audio/kit.json --out audio/kit # takes + k
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.
+ stacked attacks or a build before the hit. 185 of the 201 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).
+ seed. The three presets sound every role but riser, swell and suck, use one clean hit for the lockup, and use the
+ fitted recordings for clicks, ticks, keys, touches and the snap where they measure closer to the role than the
+ forge member (earshot match and realness).
- **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`.
diff --git a/docs/FIT.md b/docs/FIT.md
index 9f5b2ae..caece4b 100644
--- a/docs/FIT.md
+++ b/docs/FIT.md
@@ -216,6 +216,35 @@ Each comes with:
The 0.5 morphs sit between their sources: CLAP 0.48-0.76 to each, so they are new sounds, not copies.
+## Takes: a fit rendered for use (0.3)
+
+A fit is measured against a trimmed recording: the identity render (seed 0, no knobs) keeps the recording's length
+and every bit of its low end, and that is what the tables above measure. A take for a film is another job, and the
+0.2 renderer made takes with three measured defects. Since 0.3, `fit.render(model, seed, vary=v)` with `vary > 0`, or
+any render with `take=True`, renders a take (the bank renders every fit entry so):
+
+| defect in 0.2 takes | measured on | fix (take mode) |
+|---|---|---|
+| tails cut where the trimmed recording stopped: fitted modes outlive it, vary lengthens decays further, a sines residual stops on the last sample | a cut tail in the takes of 13 of 46 CC0 fits (keys, clicks, a clip, a key release, a whoosh) | modal: modes ring on until all are 60 dB under the loudest strike's mode sum, at most 0.5 x the sound's span longer (at least 60 ms; 200 ms when the modes are still above -50 dB at the cut), the added stretch fading 60 dB linear in dB. sines: renders to the last partial's release, the residual noise fading out over 60 ms past the recording |
+| a random DC offset per seed: a sines residual's lowest band is flat to DC, and its envelope spreads energy down there | takes of one whoosh at -31 to -34 dB re peak (the audit warns over -40) | takes are high-passed at 8 Hz (2nd order) |
+| a spectral model's takes 2-7 LU apart: low noise bands hold few independent bins over a short gesture, and each take was levelled by its own loudest 50 ms | a cloth whoosh 7.3 LU, a key 3.8 LU, a cape 1.4 LU over 8 seeds | each take is levelled by its expected loudest 50 ms (from the gesture) and corrected to its expected K-weighted energy: 0.45, 2.6 and 0.15 LU |
+
+Two more 0.3 changes:
+- **The sines residual follows the recording's roll-off above 16 kHz.** The top residual band is flat to Nyquist, so a
+ fit put noise above 20 kHz that a 16-20 kHz band-limited recording never had (a click: -19 dB of its energy above
+ 20 kHz against -34 dB in the recording). A sines fit now stores `residual.hf`, the residual's spectrum above
+ 16 kHz relative to 16 kHz, made monotone, and the noise follows it; `sines.hf_rolloff(x)` measures it for an older
+ model. On the six sines validation refs (mean of 6 seeds) the energy above 20 kHz moved toward the recording's
+ (click -19.5 -> -30.0 dB, recording -33.5; impact -44.8 -> -60.5, recording -62.4; whoosh -41.8 -> -60.1, recording
+ -75.3) and mel dB changed by -0.10 to +0.00.
+- **`earshot fit --takes`** scores every candidate on seeds 0, 1, 2 instead of seed 0 alone
+ (`auto.fit(seeds=auto.TAKE_SEEDS)`). A candidate with noise in it can win on one lucky draw: on 10 of the 12
+ validation refs the chosen fit's seed-0 score sat 0.1-2.4 under its mean over seeds 0-7.
+
+**The fit itself did not move.** Every identity render of the 12 validation refs is the same as in 0.2 (a hybrid's
+noise layer keeps its 0.2 levelling): seed-0 and seed-averaged quality (seeds 0-7: mel, envelope, tone, onset,
+excess, missing, CLAP) are identical, so the tables above stand.
+
## Licence
A fit of a recording is a derivative of that recording: the parameters are measured from it. Keep the source's
diff --git a/docs/SFX.md b/docs/SFX.md
index e5cd82d..681b856 100644
--- a/docs/SFX.md
+++ b/docs/SFX.md
@@ -1,9 +1,11 @@
# 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.
+earshot 0.3.0 ships its forge sounds, three tuned voices and 15 sounds fitted from public-domain recordings 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 (a
+fitted sound is stored as its modes, partials and band envelopes, not as samples). 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`) or fits
+(`earshot fit`) offline.
```bash
earshot sfx list --kind whoosh # what is in the bank
@@ -22,16 +24,17 @@ Contents: [the bank](#the-bank) · [knobs](#knobs-dur-apex-pitch-level) · [the
## The bank
-`earshot/forge/bank/*.json` (package data; the forge file is 275 KB, 64 KB gzipped): 186 sounds today.
+`earshot/forge/bank/*.json` (package data; the forge file is 275 KB, 64 KB gzipped; the fit file 0.5 MB): 201 sounds
+today. `earshot doctor` reports the version and the counts.
| file | version | entries | what |
|---|---|---|---|
| `forge_v2.json` | `forge_v2r6` | 183 | every delivered forge v2 final (34 categories, 4-6 named members each) |
+| `fit.json` | `fit1` | 15 | recipes fitted from CC0 recordings (`fit/<role>/<name>`, [below](#fit-entries-from-public-domain-recordings)) |
| `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
+`bank.VERSION` joins the file versions (`forge_v2r6+fit1+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`).
@@ -76,6 +79,7 @@ bit-exactly.
| 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) |
+| fit | the role in the id, plus its `kinds` | recordings fitted as code: clicks, a tick, pops, light touches, keys, a space bar, a snap, a bell, a whoosh, a knock |
## Knobs: dur, apex, pitch, level
@@ -154,10 +158,11 @@ bells and plucks read 0. The layer heuristic reads a 25 ms RMS envelope (peaks w
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
+Audit of the whole bank (each sound at its own seed): 185 of 201 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.
+m3 (ring). The presets use none of them. All 15 fitted sounds are clean at their own seed; on some new seeds the
+small bell and the lubed key show a comb ring in the tail, as their recordings do (the presets use neither).
## Kits
@@ -195,7 +200,7 @@ text fragment resolving). Other role names are allowed; a renderer must know the
`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",
+{"kit": 1, "earshot": "0.3.0", "bank": "forge_v2r6+fit1+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": "...",
@@ -205,8 +210,8 @@ text fragment resolving). Other role names are allowed; a renderer must know the
- **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.
+ names `seed` and `planned_seed`. On the three presets 4 of 174 takes needed it (three key takes and a pitched ding,
+ all forge members; no fitted sound); 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.
@@ -220,35 +225,58 @@ text fragment resolving). Other role names are allowed; a renderer must know the
`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.
+the lockup with nothing layered on it. Each role's `note` says what the sound is and what was measured. How the members
+were chosen:
+
+- **Every take passes the audit** (`earshot kit check`, all takes of all three presets); members the audit flags
+ (ringing keys, clicking airy ticks, rising zips) are out.
+- **Measured against the role.** Per role, the candidates (forge members and the fitted sounds) were read the same
+ way: `earshot match` of the role's description (a calibrated z, and a forced choice against three synth-blip
+ descriptions: 'a cheap synthesizer laser zap', 'a video game blip', 'an 8-bit chiptune sound'), `earshot realness`
+ (a model's reading of "a real recording": information, not a quality score) and the model-free measures (length,
+ centroid, attack, crest). A fitted sound replaced a forge member where it measured clearly closer: a higher match
+ and forced-choice score at an equal or higher realness. Where the two measured about the same, the forge member
+ stayed (calm's light touch tap/soft: z +1.88, realness 0.96, the fitted fingertip +2.07, 0.95; calm's key
+ typing_key/thock +5.74 against the fitted keys' +4.65 to +5.14).
+- **Designed where the idiom is designed**: crisp's tink, gated hit, sub drop and dings; minimal's sub-led set and its
+ high-passed key ticks.
+- **Restraint**: 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.
+- **Levels**: a role whose sound changed kept its loudness: `level_db` moved by the measured loudness difference of
+ the two sounds at the same peak (momentary-max LUFS at -1 dBFS), rounded to 0.5 dB.
| 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 |
+| tick / tick.crisp | fit/tick/domino / pro_tap/glass | fit/tick/domino / 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 |
+| land / land.light | pro_pop_in/deep / tap/soft | pro_pop_in/deep / fit/land.light/fingertip_book | pro_pop_in/deep / fit/land.light/fingertip_book |
+| pop | fit/pop/mouth_plop | pro_pop_in/round | pro_pop_in/round |
+| whoosh.short / .long | fit/whoosh.short/bamboo_swish / 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 |
+| key / .space / .return | typing_key/thock / fit/key.space/thock_space / typing_key/deep | fit/key/medium / fit/key.space/thock_space / typing_key/clicky | pro_typing_key glass / tick / double |
+| click / click.confirm | fit/click/floss_lid / pluck/kalimba_soft C6 | fit/click/floss_lid / pro_notify/ding_2045 | pro_click/soft / pro_notify/ding_1822 |
+| snap | fit/snap/switch_flip | fit/snap/switch_flip | fit/snap/switch_flip |
| 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 |
+| text | pluck/kalimba_soft C5 E5 G5 | fit/land.light/finger_phone | fit/land.light/finger_phone |
| 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.
+The replacements, measured (match z / forced choice against the synth-blip descriptions / realness; `_compare` of
+the fit run, the forge members at their own seed):
+
+| role | forge member before | fitted sound now | where |
+|---|---|---|---|
+| tick ('a soft quiet UI tick') | tap/glass -0.08 / 0.01 / 0.45 | domino +1.02 / 0.67 / 0.83 | calm, crisp |
+| click ('a soft UI button click') | tap/finger +1.37 / 0.61 / 0.89; pro_click/mouse +1.03 / 0.35 / 0.06 | floss_lid +1.70 / 0.73 / 0.97 | calm, crisp |
+| pop ('a soft natural pop') | pro_pop_in/airy +1.88 / 0.98 / 0.65 | mouth_plop +2.98 / 1.00 / 0.97 | calm |
+| land.light ('a soft finger tap on wood') | pro_tap/knock +0.13 / 0.00 / 0.28; pro_tap/finger +0.69 / 0.01 / 0.16 | fingertip_book +2.07 / 0.99 / 0.95 | crisp, minimal |
+| whoosh.short ('a short fast whoosh swish through the air') | swipe/velvet +2.01 / 1.00 / 0.97 (tagged 'a heavy thud') | bamboo_swish +5.32 / 1.00 / 0.99 | calm |
+| key ('a single mechanical keyboard key press') | typing_key/crisp +4.48 / 1.00 / 0.95 | medium +4.65 / 1.00 / 0.99 (2.2 kHz centroid against 0.6) | crisp |
+| key.space ('a spacebar press') | typing_key/deep +2.14 / 0.97 / 0.84; typing_key/thock +2.59 / 0.98 / 0.96 | thock_space +3.22 / 1.00 / 0.99 | calm, crisp |
+| snap ('a toggle switch click') | pro_pop_in/knock +0.61 / 0.27 / 0.08; toggle/latch +2.04 / 0.97 / 0.50 | switch_flip +2.24 / 1.00 / 0.97 | calm, crisp, minimal |
+| text (a soft touch for a resolving fragment) | pro_tap/soft, pro_tap/finger (realness 0.16-0.25) | finger_phone (tagged 'a soft UI button tap', realness 0.89) | crisp, minimal |
+
+Set `edits.pitch` on `hit` (calm) and `drop` (crisp, minimal) to the film's root.
## Python and MCP
@@ -266,21 +294,72 @@ 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:
+`earshot fit` turns a recording into a model ([docs/FIT.md](FIT.md)); a fitted model in a bank file is a sound like any
+other, `fit/<role>/<name>`, with its source. The bank ships 15, fitted from CC0 recordings on Freesound (credits:
+[docs/CREDITS_FIT.md](CREDITS_FIT.md)):
+
+| id | what | model | length (take) | CLAP to the recording | kinds |
+|---|---|---|---|---|---|
+| `fit/click/floss_lid` | a small plastic click | sines | 0.13 s | 0.96 | click, tick.crisp |
+| `fit/tick/domino` | domino pieces knocking together | sines | 0.14 s | 0.94 | tick |
+| `fit/pop/mouth_plop` | a soft mouth plop | hybrid | 0.28 s | 0.96 | pop |
+| `fit/pop/lip_pop` | a short pop | modal | 0.22 s | 0.95 | pop |
+| `fit/land.light/fingertip_book` | light finger steps on a book | modal | 0.38 s | 0.94 | land.light, tock |
+| `fit/land.light/finger_wood` | a finger tap on a wooden counter | modal | 0.34 s | 0.93 | land.light, tock |
+| `fit/land.light/finger_phone` | a finger tapping a phone | hybrid | 0.33 s | 0.93 | land.light, text |
+| `fit/whoosh.short/bamboo_swish` | a short whoosh | sines | 0.48 s | 0.94 | whoosh.short |
+| `fit/key/medium` | one mechanical key, press and release | hybrid | 0.43 s | 0.94 | key |
+| `fit/key/thock` | one low mechanical key press | modal | 0.45 s | 0.94 | key |
+| `fit/key/lubed` | one mechanical key press | modal | 0.42 s | 0.98 | key |
+| `fit/key.space/thock_space` | a mechanical keyboard space bar | sines | 0.39 s | 0.95 | key.space |
+| `fit/snap/switch_flip` | a switch flip | sines | 0.19 s | 0.94 | snap, click |
+| `fit/bell/small_bell` | a small bell struck once | sines | 1.66 s | 0.94 | bell |
+| `fit/hit/bamboo_tok` | a bamboo hit | hybrid | 0.17 s | 0.97 | hit, tock |
+
+Every entry renders through `earshot.forge.fit.render(model, seed, vary=vary, take=True)`: a new seed is a new take of
+the same object (modes, partials and noise jittered by `vary`, 0.3 for all 15), it rings out instead of stopping where
+the trimmed recording stopped, and it carries no DC offset (FIT.md, "Takes"). A take is 0.06-0.2 s longer than its
+recording; `max_s` in a kit trims it.
+
+**How they were chosen.** 46 CC0 recordings were fitted (`earshot fit --clap`) for the film roles. A fit ships when:
+- its grade is high: CLAP to the recording >= 0.92 and mel distance within 2.5 dB of the model's own floor (two
+ renders of the model);
+- five takes (seeds 0-4, rendered as the bank renders them, at the shipped `vary`) pass the take check: no hard
+ artifact beyond the recording's own (`polish.PolishRef`), every audit warning also on the recording itself, CLAP >=
+ 0.90 to the fit's render and within 0.06 of the fit's CLAP to the recording (compared over the recording's length:
+ CLAP repeat-pads a short clip, so another length reads as another rhythm), excess energy within 1.5 dB of the fit's,
+ loudness spread <= 2 LU. The check tries vary 0.3, then 0.15, then fresh noise only; a fit clean only with fresh
+ noise does not ship (its takes barely differ);
+- the source is CC0 1.0 and no title, author or page names a commercial sound library (a re-upload is not the
+ recordist's to release).
+
+15 of 46 pass, all at vary 0.3. Of the other 31, 20 grade good or fair; of the 11 high-grade ones, 7 make takes that
+drift from the recording (CLAP), add an artifact the recording lacks (a comb ring, a rising glide) or spread over
+2 LU, 3 are clean only with fresh noise, and one is a re-upload. Two shipped sounds, the small bell and the lubed
+key, show the comb-ring warning on some takes, as their recordings do: in a kit, such a take is re-rolled on a new
+seed (or kept with its warning when no re-roll is clean).
+
+### Add your own fit
```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": "..."}
+# 1. a CC0 / public-domain recording of ONE sound, trimmed close (a short fade-out at the cut is fine)
+earshot fit door.wav -o made/door_fit.py --clap --takes --report # model made/door_fit.json + quality + floor
+# 2. hear and audit takes the way the bank will render them
+python -c "from earshot.forge.fit import auto; from earshot.forge import sfx; import soundfile as sf; m = auto.load('made/door_fit.json'); [print(s, sfx.check(auto.render(m, seed=s, vary=0.3, take=True))['summary']) or sf.write(f'made/take{s}.wav', auto.render(m, seed=s, vary=0.3, take=True), 48000) for s in range(5)]"
+# 3. add it to a bank file of your own (or, in a checkout, the default earshot/forge/bank/fit.json)
+python -m earshot.forge.bank add-fit made/door_fit.json --id fit/hit/door --source source.json --vary 0.3 --bank my_bank.json
+# source.json: {"id": "freesound:123", "title": "...", "author": "...", "license": "CC0 1.0", "url": "https://..."}
+EARSHOT_BANK=my_bank.json earshot sfx render fit/hit/door -o door_take.wav --seed 3
```
-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`).
+- `--takes` scores the candidates on seeds 0-2 (a fit meant to make takes); `--clap` lets CLAP help choose (loads
+ CLAP, about 50 s). The report's `quality` against `floor` says how close the fit is (FIT.md, "Quality metrics").
+- Lower `--vary` (0.15, 0) when takes drift: listen to the takes, and run `earshot sfx check` on them.
+- The licence must be CC0 or public domain; `--allow-license` keeps an attribution licence (credit the source), and NC
+ or ND licences are always refused: a fit is a derivative of its recording and the bank ships in an MIT package.
+- The entry keeps the model (its fit report dropped), seed, `vary`, the source, the measured note of a tonal fit
+ (`pitch_hz`: the pitch knob tunes it through the fit's own pitch / transpose / size knob, within an octave), the
+ kinds (`--kinds`, default the role in the id) and the usual meta and fingerprint (`bank check` re-renders it).
## Cost
@@ -295,16 +374,17 @@ Measured on the development laptop (AMD Ryzen 7 260, 2 threads, while other jobs
| warm render / render + audit: whooshes, swipes, bells, sub drops | 0.1-0.45 s / 0.25-0.8 s |
| warm render / render + audit: pluck (3 s), impact (4.8 s) | 1.0-1.1 s / 1.4-2.2 s |
| a targeted whoosh (dur + apex: up to 3 renders + audit) | 1.9 s |
-| render + audit, median over all 186 sounds (a cold process per batch) | 0.5 s |
-| `kit render`, whole preset, fresh process | calm 73 s (57 takes), crisp 61 s (59), minimal 25 s (58) |
+| render + audit, median over the 186 forge sounds and plucks (a cold process per batch) | 0.5 s |
+| `kit render`, whole preset, fresh process | calm 28 s (57 takes), crisp 81 s (59), minimal 24 s (58), with the fitted sounds |
| `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.
+- The bank is the forge's sound plus 15 fitted recordings, chosen and checked by measurement; it is not a library of
+ recordings. Measurements (realness, a match against a role's description, the audit) are models and heuristics,
+ not ears: a film's own listening pass still decides.
- 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
diff --git a/earshot/forge/bank.py b/earshot/forge/bank.py
index 370733c..266f592 100644
--- a/earshot/forge/bank.py
+++ b/earshot/forge/bank.py
@@ -1,7 +1,7 @@
"""The shipped sound bank: every delivered forge v2 final, tuned plucks and fitted recipes, rendered by id.
from earshot.forge import bank
- bank.VERSION # 'forge_v2r6+pluck1' (one tag per bank file)
+ bank.VERSION # 'forge_v2r6+fit1+pluck1' (one tag per bank file)
bank.list(kind='whoosh') # [{id, category, member, type, dur_s, peak_s, onset_s, ...}, ...]
y, meta = bank.render('whoosh_fast/crisp') # the delivered final (its own seed), peak -1 dBFS, float32
y, meta = bank.render('whoosh_fast/crisp', seed=7, dur=0.8, apex=0.32) # a new take aimed at the picture
diff --git a/skills/earshot/SKILL.md b/skills/earshot/SKILL.md
index cbe5a0a..bd81d24 100644
--- a/skills/earshot/SKILL.md
+++ b/skills/earshot/SKILL.md
@@ -157,9 +157,11 @@ bank instead of writing synth voices. No models load; a whole kit renders in abo
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`.
+Say plainly what the bank is: forge sounds made in code, and 15 sounds fitted as code from CC0 recordings
+(`fit/<role>/<name>`, each with its source; the presets use them for clicks, ticks, keys, touches and the snap), all
+chosen and checked by measurement. They are not recordings: when the brief asks for recorded sound, use
+`skills/real-sound` instead. To add a fit of your own (`earshot fit --takes`, then `bank add-fit`), see `docs/SFX.md`
+("Add your own fit").
## 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 for