Ears for coding agents: let AI hear, review and make sound. CPU-only, open source.
earshot kit: film sound kits from the bank (init / render / check / audition), presets, API and MCP tools
Leonxlnx8920752caf4d
diff --git a/earshot/api.py b/earshot/api.pyindex 8fda9a7..d418dd0 100644--- a/earshot/api.py+++ b/earshot/api.py@@ -5,6 +5,8 @@api.match('key.ogg', 'a deep thocky mechanical keyboard press', alts=['a clicky blue switch'])api.find('typing.ogg', 'a single isolated key press')api.timeline('soundtrack.wav', video='film.mp4')+ api.sfx_render('whoosh_fast/crisp', 'w.wav', dur=0.8, apex=0.32) # the sound bank (earshot.forge.bank)+ api.kit_render('audio/kit.json', 'audio/kit') # a film's kit: takes + kit.lock.json"""import importlib@@ -14,6 +16,11 @@ _FUNCS = {'realness': ('realness', 'realness'), 'realness_many': ('realness', 'realness_many'), 'timeline': ('timeline', 'timeline'), 'sheet': ('sheet', 'sheet'),'critique': ('critique', 'critique'), 'profile': ('profile', 'profile'), 'measure': ('features', 'measure'),'llm_critique': ('llm', 'critique'), 'doctor': ('doctor', 'check'),+ # the sound bank and film kits (no models): earshot.forge.sfx / earshot.forge.kit+ 'sfx_list': ('forge.sfx', 'sfx_list'), 'sfx_render': ('forge.sfx', 'sfx_render'),+ 'sfx_check': ('forge.sfx', 'sfx_check'), 'kit_init': ('forge.kit', 'kit_init'),+ 'kit_render': ('forge.kit', 'kit_render'), 'kit_check': ('forge.kit', 'kit_check'),+ 'kit_audition': ('forge.kit', 'kit_audition'),}diff --git a/earshot/cli.py b/earshot/cli.pyindex cf9d625..a064584 100644--- a/earshot/cli.py+++ b/earshot/cli.py@@ -27,6 +27,8 @@ COMMANDS = {'profile': 'profile', # build a reference profile from your own reference films'forge': 'forge', # make sounds in code and improve them by listening'fit': 'forge.fit', # translate a recording into code (analysis by synthesis) and vary it+ 'sfx': 'forge.sfx', # one sound of the shipped bank by id, aimed at the picture; audit any sound effect+ 'kit': 'forge.kit', # a film's sound kit: one bank sound per role, rendered to takes with sync points'gallery': 'gallery', # one static HTML page of forge results: players, spectrograms, numbers'measure': 'features', # objective measurements only (no models)'llm': 'llm', # optional audio-LLM critique (only with your own API key + consent)diff --git a/earshot/forge/kit.py b/earshot/forge/kit.pynew file mode 100644index 0000000..c8ef278--- /dev/null+++ b/earshot/forge/kit.py@@ -0,0 +1,506 @@+"""earshot kit: one film's sounds by role, rendered from the bank into takes with measured sync points.++ earshot kit init --preset calm -o audio/kit.json # calm | crisp | minimal (earshot/forge/kits)+ earshot kit render audio/kit.json --out audio/kit [--force] # cached; writes audio/kit/kit.lock.json+ earshot kit check audio/kit.json [--out audio/kit] [--json] # ids, knobs, the model-free audit of every take+ earshot kit audition audio/kit.json -o audition.wav [--out audio/kit] # every take, role by role, at its level++ from earshot.forge import kit+ lock = kit.render('audio/kit.json', 'audio/kit') # the lock dict (also written as kit.lock.json)++A kit names a bank sound per role (the shared vocabulary of a film's cue kinds and their variants, ROLES) and how to+render it; a renderer (cinetic's score.py, a mixer) places the takes by the measured onset / peak / end in the lock.++kit.json (schema 1):+ {"kit": 1, "name": "calm", "sr": 48000,+ "roles": {"hit": {"sound": "notify/m0", "takes": 3, "seed": 1, "edits": {"dur": 1.6}, "align": "onset",+ "max_s": 2.0, "level_db": -2.0, "note": "why this sound"},+ "bell": {"sound": "pluck/kalimba", "pitches": ["C5", "D5", "E5", "G5", "A5"], "align": "onset"},+ "riser": null},+ "off": {"riser": "why this role is off"}}+ sound a bank id (`earshot sfx list`), forge, pluck/* or fit/*+ takes how many takes (default 1, at most 32); take k renders with seed + k - 1 (seed default: the sound's own,+ so take 1 is the delivered final). A take that fails the audit is rendered again on seed + 1000 j (up to+ REROLL times) and the first clean one kept (the lock names it, with planned_seed). Same kit, same takes:+ rendering is deterministic.+ edits knobs for every take: dur, apex, pitch, peak_db (default -1), weight (earshot.forge.knobs, bank.render)+ pitches one set of takes per pitch (note names or Hz), through the recipe's own pitch parameter+ align the sync point a mixer puts on the cue: onset (the take's measured onset), peak (its loudest 5 ms: whoosh+ apexes), end (its end: risers, swells); default ALIGN[role]+ max_s a take longer than this is faded out to it (a quarter of the length, at most 150 ms)+ level_db the mix level of the role relative to a take at its peak: information for the mixer (audition uses it)+ note why this sound (the presets say why for every role; "off" says why a role is null)+ null the role is not sounded: a renderer skips such cues (the presets keep riser, swell and suck off)++kit.lock.json (written by render into --out with the takes):+ {"kit": 1, "earshot": "0.3.0", "bank": "<bank.VERSION>", "sr": 48000, "name": "calm",+ "roles": {"hit": {"sound": "notify/m0", "align": "onset", "level_db": -2.0, "max_s": 2.0,+ "takes": [{"file": "hit_1.wav", "seed": 1, "pitch": null, "onset_s": 0.0, "peak_s": 0.004,+ "end_s": 1.6, "dur_s": 1.6, "peak_db": -1.0, "lufs_m_max": -11.1, "sha1": "...",+ "key": "...", "checks": []}]},+ "riser": null}}+Takes are 24-bit WAVs named <role>_<k>.wav (dots in a role become '-': tick-crisp_1.wav) or <role>_<pitch>[_k].wav+(C#5 -> Cs5). The cache: 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 as it is; --force renders everything; files of the old lock+that the new kit no longer names are removed (only those). `checks` lists the warning codes of the take's audit+(earshot.forge.sfx.check with the role as context: a hit warns on stacked attacks and pre-swells).+"""+import hashlib+import json+import os+import re+import time++import numpy as np++from ..report import emit++SR = 48000+SCHEMA = 1+KITS_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'kits')+LOCK = 'kit.lock.json'+ROLES = ('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')+ALIGN = {'whoosh.short': 'peak', 'whoosh.long': 'peak', 'suck': 'end', 'riser': 'end', 'swell': 'end'}+ALIGNS = ('onset', 'peak', 'end')+EDITS = ('dur', 'apex', 'pitch', 'peak_db', 'weight')+ROLE_KEYS = ('sound', 'takes', 'seed', 'edits', 'pitches', 'align', 'max_s', 'level_db', 'note')+MAX_TAKES = 32+REROLL = 3 # extra seeds a take that fails the audit may try (render_take)+RESTRAINED = ('riser', 'swell', 'suck')+# sounds the presets never use, with the reason (kit check notes them; the choice stays the kit author's)+NEVER = {'pro_zip/up': 'rises in pitch (a synth whip)', 'pro_zip/up_hi': 'rises in pitch (a synth whip)',+ 'pro_zip/arc': 'rises in pitch (a synth whip)', 'riser/shepard': 'a shepard riser',+ 'downlifter/shepard_fall': 'a shepard downlifter', 'downlifter/synth_fall': 'a synth downlifter'}+NEVER_CATEGORIES = {'logo_sting': 'a composite sting (lead-in + hit + chime stacked)',+ 'pro_logo_sting': 'a composite launch gesture', 'shimmer': 'a shimmer wash',+ 'pro_shimmer': 'a granular shimmer', 'glitch': 'a glitch', 'pro_glitch': 'a glitch',+ 'pro_pop': 'tonal pops (the 8-bit risk the forge measured)'}+++class KitError(ValueError):+ """an invalid kit file"""+++# ----------------------------------------------------------------------------------------------- files and checks+def presets():+ return sorted(os.path.splitext(f)[0] for f in os.listdir(KITS_DIR) if f.endswith('.json'))+++def preset(name):+ p = os.path.join(KITS_DIR, f'{name}.json')+ if not os.path.isfile(p):+ raise KitError(f'no preset {name!r} (presets: {", ".join(presets())})')+ with open(p, encoding='utf-8') as fh:+ return json.load(fh)+++def load(kit):+ """a kit dict from a path (or the dict itself), validated: KitError lists every problem"""+ if isinstance(kit, str):+ with open(kit, encoding='utf-8') as fh:+ try:+ kit = json.load(fh)+ except json.JSONDecodeError as e:+ raise KitError(f'{kit}: not JSON ({e})') from None+ bad = problems(kit)+ if bad:+ raise KitError('invalid kit: ' + '; '.join(bad))+ return kit+++def problems(kit):+ """what is wrong with a kit dict (schema, roles, ids, knob names); [] when it is valid"""+ from . import bank+ out = []+ if not isinstance(kit, dict) or kit.get('kit') != SCHEMA:+ return [f'not a kit file (needs "kit": {SCHEMA})']+ if int(kit.get('sr', SR)) not in (44100, 48000, 88200, 96000):+ out.append(f"sr {kit.get('sr')}: use 48000 (or 44100 / 88200 / 96000)")+ roles = kit.get('roles')+ if not isinstance(roles, dict) or not roles:+ return out + ['roles: a non-empty object {role: spec | null}']+ known = set(bank.ids())+ for role, spec in roles.items():+ if not re.fullmatch(r'[a-z][a-z0-9_]*(\.[a-z0-9_]+)*', str(role)):+ out.append(f'role {role!r}: lowercase words joined by dots (hit, whoosh.short)')+ if spec is None:+ continue+ if not isinstance(spec, dict):+ out.append(f'{role}: a spec object or null')+ continue+ extra = set(spec) - set(ROLE_KEYS)+ if extra:+ out.append(f'{role}: unknown keys {sorted(extra)} (known: {", ".join(ROLE_KEYS)})')+ sid = spec.get('sound')+ if sid not in known:+ from difflib import get_close_matches+ near = get_close_matches(str(sid), sorted(known), n=3, cutoff=0.5)+ out.append(f'{role}: unknown sound {sid!r}' + (f' (did you mean {", ".join(near)}?)' if near else ''))+ t = spec.get('takes', 1)+ if not isinstance(t, int) or isinstance(t, bool) or not 1 <= t <= MAX_TAKES:+ out.append(f'{role}: takes must be an integer 1-{MAX_TAKES}')+ if spec.get('seed') is not None and (not isinstance(spec['seed'], int) or isinstance(spec['seed'], bool)):+ out.append(f'{role}: seed must be an integer')+ ed = spec.get('edits') or {}+ if not isinstance(ed, dict) or set(ed) - set(EDITS):+ out.append(f'{role}: edits takes {", ".join(EDITS)}')+ ps = spec.get('pitches')+ if ps is not None and (not isinstance(ps, list) or not ps):+ out.append(f'{role}: pitches must be a non-empty list of notes / Hz')+ if ps and isinstance(ed, dict) and ed.get('pitch') is not None:+ out.append(f'{role}: give edits.pitch or pitches, not both')+ if spec.get('align', ALIGN.get(role, 'onset')) not in ALIGNS:+ out.append(f'{role}: align must be one of {", ".join(ALIGNS)}')+ for k in ('max_s', 'level_db'):+ if spec.get(k) is not None and not isinstance(spec[k], (int, float)):+ out.append(f'{role}: {k} must be a number')+ return out+++def init(preset_name='calm', out='audio/kit.json', force=False):+ """write a preset as a film's kit file: {'summary', 'file', 'kit'}"""+ k = preset(preset_name)+ if os.path.exists(out) and not force:+ raise KitError(f'{out} exists (force=True / --force overwrites it)')+ os.makedirs(os.path.dirname(os.path.abspath(out)), exist_ok=True)+ with open(out, 'w', encoding='utf-8', newline='\n') as fh:+ fh.write(json.dumps(k, indent=1, ensure_ascii=False) + '\n')+ on = [r for r, s in k['roles'].items() if s]+ return {'summary': f"wrote {out}: preset {preset_name}, {len(on)} roles sounded, "+ f"{len(k['roles']) - len(on)} off ({', '.join(r for r, s in k['roles'].items() if not s)})",+ 'file': out.replace(chr(92), '/'), 'kit': k}+++# ------------------------------------------------------------------------------------------------------- planning+def _label(p):+ from .knobs import midi+ s = str(p).strip()+ if midi(s) is not None:+ return s.replace('#', 's')+ return re.sub(r'[^0-9a-zA-Z.]+', '', s.lower().replace('hz', '')) + 'hz'+++def plan(kit):+ """the takes a kit renders: [{role, file, sound, seed, pitch, edits, max_s, k}]"""+ from . import bank+ out = []+ for role, spec in kit['roles'].items():+ if not spec:+ continue+ e = bank.get(spec['sound'])+ base = int(spec['seed']) if spec.get('seed') is not None else int(e['seed'])+ n = int(spec.get('takes', 1))+ stem = role.replace('.', '-')+ ed = dict(spec.get('edits') or {})+ pitches = spec.get('pitches') or [ed.pop('pitch', None)]+ ed.pop('pitch', None)+ for p in pitches:+ for k in range(1, n + 1):+ name = stem + (f'_{_label(p)}' if spec.get('pitches') else '') + (+ f'_{k}' if (n > 1 or not spec.get('pitches')) else '')+ out.append({'role': role, 'file': name + '.wav', 'sound': spec['sound'], 'seed': base + k - 1,+ 'pitch': p, 'edits': ed, 'max_s': spec.get('max_s'), 'k': k})+ return out+++def _digest(o):+ return hashlib.sha1(json.dumps(o, sort_keys=True, separators=(',', ':'), default=str).encode()).hexdigest()+++def take_key(t, sr=SR):+ """the cache key of one planned take (module doc)"""+ from .. import __version__+ from . import bank+ return _digest({'sound': t['sound'], 'entry': _digest(bank.get(t['sound'])), 'seed': t['seed'],+ 'pitch': t['pitch'], 'edits': t['edits'], 'max_s': t['max_s'], 'sr': int(sr),+ 'bank': bank.VERSION, 'earshot': __version__})+++def _sha1(path):+ with open(path, 'rb') as fh:+ return hashlib.sha1(fh.read()).hexdigest()+++def _render_one(t, seed, role):+ from . import bank, knobs, sfx+ ed = t['edits']+ y, meta = bank.render(t['sound'], seed=seed, dur=ed.get('dur'), apex=ed.get('apex'), pitch=t['pitch'],+ peak_db=ed.get('peak_db', -1.0), weight=ed.get('weight'), checks=False)+ if t['max_s'] and len(y) > t['max_s'] * SR:+ y = knobs.fit_length(y, float(t['max_s']))[0].astype(np.float32)+ c = sfx.check(y, category=bank.get(t['sound'])['category'], role=role or t['role'], sound=t['sound'])+ return y, c, meta+++def render_take(t, role=None):+ """one planned take at 48 kHz: (y float32, check dict, meta, the seed used). max_s applied, audited with the+ role as context; a take that fails the audit is rendered again on seed + 1000 j (j = 1 .. REROLL) and the first+ clean one is kept, like a sound designer discarding a bad take (measured on the presets: about 1 take in 20 of+ a new seed rings or stops early); when none is clean the planned seed's take is kept with its warnings."""+ first = None+ for j in range(REROLL + 1):+ s = int(t['seed']) + 1000 * j+ y, c, meta = _render_one(t, s, role)+ if c['ok']:+ return y, c, meta, s+ first = first or (y, c, meta, s)+ return first+++# ------------------------------------------------------------------------------------------------------ rendering+def _read_lock(out):+ p = os.path.join(out, LOCK)+ if not os.path.isfile(p):+ return None+ try:+ with open(p, encoding='utf-8') as fh:+ return json.load(fh)+ except (OSError, json.JSONDecodeError):+ return None+++def render(kit, out, force=False, log=None):+ """render every take of a kit into `out` (cached, module doc) and write out/kit.lock.json; returns the lock dict+ plus 'summary' and 'stats' {takes, rendered, cached, removed, seconds}"""+ from .. import __version__+ from . import bank, sfx+ t0 = time.perf_counter()+ k = load(kit)+ sr = int(k.get('sr', SR))+ os.makedirs(out, exist_ok=True)+ old = _read_lock(out) or {}+ cache = {}+ for r in (old.get('roles') or {}).values():+ for tk in (r or {}).get('takes') or []:+ cache[(tk.get('key'), tk.get('file'))] = tk+ lock = {'kit': SCHEMA, 'earshot': __version__, 'bank': bank.VERSION, 'sr': sr, 'name': k.get('name'),+ 'roles': {}}+ for role, spec in k['roles'].items():+ lock['roles'][role] = None if not spec else {+ 'sound': spec['sound'], 'align': spec.get('align', ALIGN.get(role, 'onset')),+ 'level_db': float(spec.get('level_db', 0.0)), 'max_s': spec.get('max_s'), 'takes': []}+ rendered = cached = 0+ for t in plan(k):+ key = take_key(t, sr)+ path = os.path.join(out, t['file'])+ hit = cache.get((key, t['file']))+ if not force and hit and os.path.isfile(path) and _sha1(path) == hit.get('sha1'):+ lock['roles'][t['role']]['takes'].append(hit)+ cached += 1+ continue+ y, c, _, used = render_take(t)+ m = bank.measure(y)+ if sr != SR:+ import soxr+ y = np.asarray(soxr.resample(y, SR, sr), np.float32)+ sfx.write(path, y, sr)+ rec = {'file': t['file'], 'seed': used, 'pitch': t['pitch'], **{x: m[x] for x in (+ 'onset_s', 'peak_s', 'end_s', 'dur_s', 'peak_db', 'lufs_m_max')}, 'sha1': _sha1(path), 'key': key,+ 'checks': [w['code'] for w in c['warnings']]}+ if used != t['seed']:+ rec['planned_seed'] = t['seed']+ lock['roles'][t['role']]['takes'].append(rec)+ rendered += 1+ if log:+ log(f" {t['file']:24s} {t['sound']:26s} seed {t['seed']:<11d} {m['dur_s']:6.3f} s"+ + (f" WARN {', '.join(rec['checks'])}" if rec['checks'] else ''))+ keep = {tk['file'] for r in lock['roles'].values() if r for tk in r['takes']}+ removed = 0+ for r in (old.get('roles') or {}).values():+ for tk in (r or {}).get('takes') or []:+ f = tk.get('file')+ if f and f not in keep and os.path.basename(f) == f and os.path.isfile(os.path.join(out, f)):+ os.remove(os.path.join(out, f))+ removed += 1+ path = os.path.join(out, LOCK)+ with open(path + '.tmp', 'w', encoding='utf-8', newline='\n') as fh:+ fh.write(json.dumps(lock, indent=1) + '\n')+ os.replace(path + '.tmp', path)+ n = rendered + cached+ warn = sorted({f"{r}:{c}" for r, v in lock['roles'].items() if v for tk in v['takes'] for c in tk['checks']})+ dt = time.perf_counter() - t0+ lock_out = dict(lock)+ lock_out['stats'] = {'takes': n, 'rendered': rendered, 'cached': cached, 'removed': removed,+ 'seconds': round(dt, 2)}+ lock_out['summary'] = (f"kit {k.get('name') or ''}: {n} takes in {out} ({rendered} rendered, {cached} cached"+ + (f', {removed} stale removed' if removed else '') + f') in {dt:.1f} s; '+ + ('checks clean' if not warn else 'warnings: ' + ', '.join(warn)))+ lock_out['file'] = path.replace(chr(92), '/')+ return lock_out+++def check(kit, out=None, log=None):+ """validate a kit and audit every take (the rendered files in `out` when the lock there is current for them,+ else renders in memory): {'ok', 'summary', 'problems', 'roles': {role: [take rows]}, 'notes'}"""+ from . import bank, sfx+ try:+ if isinstance(kit, dict):+ k = kit+ else:+ with open(kit, encoding='utf-8') as fh:+ k = json.load(fh)+ except (OSError, json.JSONDecodeError) as e:+ return {'ok': False, 'summary': f'kit unreadable: {e}', 'problems': [str(e)], 'roles': {}, 'notes': []}+ probs = problems(k)+ if probs:+ return {'ok': False, 'summary': f'{len(probs)} problem(s): ' + '; '.join(probs), 'problems': probs,+ 'roles': {}, 'notes': []}+ notes = []+ for role, spec in k['roles'].items():+ if role.split('.')[0] in RESTRAINED and spec:+ notes.append(f'{role} is sounded: the presets keep {", ".join(RESTRAINED)} off (one clean element on a '+ 'reveal reads better than a build stacked onto it)')+ if spec:+ cat = spec['sound'].split('/')[0]+ why = NEVER.get(spec['sound']) or NEVER_CATEGORIES.get(cat)+ if why:+ notes.append(f"{role}: {spec['sound']} is {why}; the presets never use it")+ if role.split('.')[0] not in {r.split('.')[0] for r in ROLES}:+ notes.append(f'{role}: not one of the shared roles ({", ".join(ROLES)}); a renderer must know it')+ lock = _read_lock(out) if out else None+ have = {}+ for r in ((lock or {}).get('roles') or {}).values():+ for tk in (r or {}).get('takes') or []:+ have[tk.get('key')] = tk+ sr = int(k.get('sr', SR))+ rows, bad = {}, 0+ for t in plan(k):+ row = {'file': t['file'], 'sound': t['sound'], 'seed': t['seed'], 'pitch': t['pitch']}+ try:+ tk = have.get(take_key(t, sr))+ if tk and os.path.isfile(os.path.join(out, tk['file'])):+ c = sfx.check(os.path.join(out, tk['file']), category=bank.get(t['sound'])['category'],+ role=t['role'], sound=t['sound'])+ row['source'] = 'rendered file'+ else:+ _, c, _, used = render_take(t)+ row['source'] = 'rendered in memory'+ if used != t['seed']:+ row['seed'], row['planned_seed'] = used, t['seed']+ row.update(ok=c['ok'], warnings=c['warnings'], notes=c['notes'])+ except Exception as e: # a knob a sound cannot take: say which, keep checking the rest+ row.update(ok=False, warnings=[{'code': 'render', 'msg': f'{type(e).__name__}: {e}'}], notes=[])+ bad += not row['ok']+ rows.setdefault(t['role'], []).append(row)+ if log:+ log(f" {t['file']:24s} {t['sound']:26s} " + ('ok' if row['ok'] else '; '.join(+ w['msg'] for w in row['warnings'])))+ n = sum(len(v) for v in rows.values())+ off = [r for r, s in k['roles'].items() if not s]+ warned = [f"{r['file']}: {', '.join(w['code'] for w in r['warnings'])}" for v in rows.values() for r in v+ if not r['ok']]+ summary = (f"kit {k.get('name') or ''}: {n - bad} / {n} takes clean"+ + (f", {bad} with warnings: " + '; '.join(warned) if warned else '')+ + (f"; off: {', '.join(off)}" if off else '') + (f'; {len(notes)} note(s)' if notes else ''))+ return {'ok': not bad, 'summary': summary, 'problems': [], 'roles': rows, 'notes': notes}+++def audition(kit, out_wav, takes=None, gap_s=0.3, role_gap_s=0.8):+ """every take of a kit in role order, each at its role's level_db, into one WAV (renders the takes first, cached+ in `takes` or in EARSHOT_HOME/kits/<name>_<hash>): {'summary', 'file', 'index': [{t, role, file, sound}]}"""+ from .. import config+ from . import sfx+ k = load(kit)+ if takes is None:+ takes = os.path.join(config.HOME, 'kits', f"{k.get('name') or 'kit'}_{_digest(k)[:10]}")+ lock = render(k, takes)+ import soundfile as sf+ parts, index, t = [], [], 0.0+ sr = lock['sr']+ for role, r in lock['roles'].items():+ if not r:+ continue+ g = 10 ** (float(r.get('level_db') or 0.0) / 20)+ for tk in r['takes']:+ y, fs = sf.read(os.path.join(takes, tk['file']), always_2d=True, dtype='float32')+ y = np.repeat(y, 2, 1) if y.shape[1] == 1 else y[:, :2]+ index.append({'t': round(t, 3), 'role': role, 'file': tk['file'], 'sound': r['sound'],+ 'pitch': tk.get('pitch')})+ parts.append(y * g)+ parts.append(np.zeros((int(gap_s * sr), 2), np.float32))+ t += len(y) / sr + gap_s+ parts.append(np.zeros((int(role_gap_s * sr), 2), np.float32))+ t += role_gap_s+ if not parts:+ raise KitError('the kit sounds no role')+ y = np.concatenate(parts)+ pk = np.abs(y).max()+ if pk > 10 ** (-1 / 20): # level_db above 0 on a -1 dBFS take: keep the audition unclipped+ y *= 10 ** (-1 / 20) / pk+ f = sfx.write(out_wav, y, sr)+ with open(os.path.splitext(out_wav)[0] + '.txt', 'w', encoding='utf-8', newline='\n') as fh:+ fh.write('\n'.join(f"{i['t']:8.3f} {i['role']:14s} {i['sound']:26s} {i['file']}" for i in index) + '\n')+ return {'summary': f"wrote {f}: {len(index)} takes of {len({i['role'] for i in index})} roles, "+ f"{len(y) / sr:.1f} s (index in {os.path.splitext(f)[0]}.txt)",+ 'file': f, 'index': index, 'takes_dir': takes.replace(chr(92), '/')}+++# --------------------------------------------------------------------------------------------------- the API+def kit_init(preset='calm', out='audio/kit.json', force=False):+ return init(preset, out, force)+++def kit_render(kit, out, force=False):+ return render(kit, out, force)+++def kit_check(kit, out=None):+ return check(kit, out)+++def kit_audition(kit, out, takes=None):+ return audition(kit, out, takes)+++# ------------------------------------------------------------------------------------------------------------ CLI+def _flags(p):+ """--json and --threads: the kit commands that take a folder use --out for it, not for a JSON copy"""+ import argparse+ p.add_argument('--json', action='store_true', help='print the full result as JSON')+ p.add_argument('--threads', type=int, default=argparse.SUPPRESS, help='CPU threads (default EARSHOT_THREADS)')+ return p+++def add_cli(sub):+ from ..cli import common+ p = sub.add_parser('kit', help="a film's sound kit: one bank sound per role, rendered to takes with measured "+ 'sync points (no models)')+ s = p.add_subparsers(dest='kit_cmd', metavar='<init|render|check|audition>')+ pi = common(s.add_parser('init', help='write a preset kit file'))+ pi.add_argument('--preset', default='calm', help='calm (text-led films, default), crisp, minimal')+ pi.add_argument('-o', '--output', default='audio/kit.json')+ pi.add_argument('--force', action='store_true', help='overwrite an existing file')+ pr = _flags(s.add_parser('render', help='render every take (cached) and write kit.lock.json'))+ pr.add_argument('kit')+ pr.add_argument('--out', dest='takes', required=True, help='folder for the takes and kit.lock.json')+ pr.add_argument('--force', action='store_true', help='render every take again')+ pc = _flags(s.add_parser('check', help='validate the kit and audit every take (model-free)'))+ pc.add_argument('kit')+ pc.add_argument('--out', dest='takes', help='the rendered takes, when current (else rendered in memory)')+ pa = _flags(s.add_parser('audition', help='every take in role order into one WAV'))+ pa.add_argument('kit')+ pa.add_argument('-o', '--output', required=True, help='audition WAV (an index .txt is written next to it)')+ pa.add_argument('--out', dest='takes', help='folder of the takes (default: a cache folder in EARSHOT_HOME)')++ def run(a):+ if a.kit_cmd == 'init':+ r = init(a.preset, a.output, a.force)+ emit(r, a, text=r['summary'])+ return 0+ if a.kit_cmd == 'render':+ r = render(a.kit, a.takes, a.force, log=None if a.json else print)+ emit(r, a, text=r['summary'])+ return 0+ if a.kit_cmd == 'check':+ r = check(a.kit, a.takes, log=None if a.json else print)+ emit(r, a, text='\n'.join([r['summary']] + [f'note: {n}' for n in r['notes']]))+ return 0 if r['ok'] else 1+ if a.kit_cmd == 'audition':+ r = audition(a.kit, a.output, a.takes)+ emit(r, a, text=r['summary'])+ return 0+ p.print_help()+ return 2+ p.set_defaults(func=run)+ return pdiff --git a/earshot/forge/kits/calm.json b/earshot/forge/kits/calm.jsonnew file mode 100644index 0000000..48b43d4--- /dev/null+++ b/earshot/forge/kits/calm.json@@ -0,0 +1,52 @@+{+ "kit": 1,+ "name": "calm",+ "sr": 48000,+ "note": "The default for text-led films: soft natural touches, one tuned voice for bells and text, gentle air for moves, a single struck note for the lockup. Members come from the families listeners took for recordings in earshot's blind test (taps, struck bells; the pluck is the launch film's measured kalimba) and pass the model-free audit (earshot kit check). Riser, swell, suck and drop are off: a reveal resolves on one element.",+ "roles": {+ "tick": {"sound": "tap/glass", "takes": 3, "align": "onset", "level_db": -8.0,+ "note": "a light fingertip on glass (80 ms tail, 466 Hz centroid): the tap family read as recorded in the blind test, where designed hover ticks were picked out"},+ "tick.crisp": {"sound": "pro_tap/glass", "takes": 3, "align": "onset", "level_db": -8.0,+ "note": "the same glass touch, tighter (98 ms, 225 Hz body + glass partial): crisp without a synthetic tink"},+ "tock": {"sound": "tap/knuckle", "takes": 3, "align": "onset", "level_db": -6.0,+ "note": "a knuckle knock: the low partner of the glass tick"},+ "hit": {"sound": "notify/m0", "takes": 2, "align": "onset", "level_db": -3.0,+ "note": "the lockup as one struck C5 bell (single attack, no build, 1.9 s natural decay): a soft tonal resolve instead of a boom; set edits.pitch to the film's root"},+ "land": {"sound": "pro_pop_in/deep", "takes": 3, "align": "onset", "level_db": -5.0,+ "note": "a round low thump (75 Hz body, 0.18 s): an element settling, felt more than heard"},+ "land.light": {"sound": "tap/soft", "takes": 3, "align": "onset", "level_db": -8.0,+ "note": "a soft fingertip thump for small elements landing"},+ "pop": {"sound": "pro_pop_in/airy", "takes": 4, "align": "onset", "level_db": -6.0,+ "note": "an airy pop-in thump with no pitch glide: tonal pops risk the 8-bit read"},+ "whoosh.short": {"sound": "swipe/velvet", "takes": 3, "align": "peak", "level_db": -7.0,+ "note": "a velvet swipe: dark cloth air (227 Hz centroid), one smooth pass, no whistle"},+ "whoosh.long": {"sound": "whoosh_big/swell", "takes": 2, "align": "peak", "level_db": -7.0,+ "note": "a gentle air swell (1.36 s, peak at 0.44 s) for scene moves: air, not a sub-led designed whoosh"},+ "suck": null,+ "riser": null,+ "drop": null,+ "key": {"sound": "typing_key/thock", "takes": 12, "align": "onset", "level_db": -10.0,+ "note": "a thocky mechanical key, a new take per keystroke; the light / laptop members ring (comb ring in the audit)"},+ "key.space": {"sound": "typing_key/deep", "takes": 4, "align": "onset", "level_db": -9.0,+ "note": "the deeper, longer cap (982 Hz centroid) stands in for the space bar"},+ "key.return": {"sound": "typing_key/deep", "takes": 2, "seed": 4100, "align": "onset", "level_db": -7.0,+ "note": "the deep cap pressed firmer: return lands 2 dB over the space bar"},+ "click": {"sound": "tap/finger", "takes": 2, "align": "onset", "level_db": -8.0,+ "note": "a fingertip tap for cursor presses: listeners picked the designed clicks out in the blind test"},+ "click.confirm": {"sound": "pluck/kalimba_soft", "takes": 1, "seed": 8101, "edits": {"pitch": "C6"}, "align": "onset", "level_db": -10.0,+ "note": "a soft tuned pluck confirms: the same voice as bell and text, quieter"},+ "snap": {"sound": "pro_pop_in/knock", "takes": 2, "align": "onset", "level_db": -6.0,+ "note": "a firm short knock for a lock-in (one attack); toggles were picked out in the blind test"},+ "swell": null,+ "bell": {"sound": "pluck/kalimba", "pitches": ["C5", "D5", "E5", "G5", "A5"], "takes": 1, "align": "onset", "level_db": -5.0,+ "note": "the launch film's kalimba on a C pentatonic: one tuned note per progress step or motif note"},+ "text": {"sound": "pluck/kalimba_soft", "pitches": ["C5", "E5", "G5"], "takes": 1, "align": "onset", "level_db": -12.0,+ "note": "one soft tuned note when a text fragment resolves (not per word), rotating through the chord, under the picture"}+ },+ "off": {+ "suck": "off by default: a reverse whoosh into a cut stacks a build onto the reveal",+ "riser": "off by default: a reveal resolves on one element; add pro_riser/air_gate only if the treatment needs a build",+ "drop": "a calm film resolves without a sub drop; pro_sub_drop/soft tuned to the root is the restrained choice if weight is needed",+ "swell": "off by default: a reverse swell before a hit is a stacked lead-in"+ }+}diff --git a/earshot/forge/kits/crisp.json b/earshot/forge/kits/crisp.jsonnew file mode 100644index 0000000..c33ea9b--- /dev/null+++ b/earshot/forge/kits/crisp.json@@ -0,0 +1,52 @@+{+ "kit": 1,+ "name": "crisp",+ "sr": 48000,+ "note": "Energetic dev-tool and product films: tight UI ticks and clicks, fast air for moves, one clean gated hit, a short tuned sub drop. Designed members where the idiom is designed (UI clicks, the gated hit), natural taps elsewhere; every member passes the model-free audit. Riser, swell and suck are off.",+ "roles": {+ "tick": {"sound": "tap/glass", "takes": 3, "align": "onset", "level_db": -8.0,+ "note": "a light glass touch: natural ticks for counters and list rows"},+ "tick.crisp": {"sound": "pro_click/tink", "takes": 3, "align": "onset", "level_db": -10.0,+ "note": "a bright designed tink (37 ms, single attack): the precise UI tick; keep it quiet"},+ "tock": {"sound": "tap/knuckle", "takes": 3, "align": "onset", "level_db": -6.0,+ "note": "a knuckle knock: the low partner of the tick"},+ "hit": {"sound": "pro_impact/short", "takes": 3, "align": "onset", "level_db": 0.0,+ "note": "one clean gated hit: a single attack, no build (pre-swell 10 ms), 0.67 s; nothing layered on it"},+ "land": {"sound": "pro_pop_in/deep", "takes": 3, "align": "onset", "level_db": -4.0,+ "note": "a round low thump for heavier elements landing"},+ "land.light": {"sound": "pro_tap/knock", "takes": 3, "align": "onset", "level_db": -7.0,+ "note": "a tight knock (86 ms) for small elements landing"},+ "pop": {"sound": "pro_pop_in/round", "takes": 4, "align": "onset", "level_db": -6.0,+ "note": "a round pop-in thump, no pitch glide: runs of pop-ins stay out of the 8-bit read"},+ "whoosh.short": {"sound": "whoosh_fast/tight", "takes": 3, "align": "peak", "level_db": -6.0,+ "note": "a tight fast pass (0.54 s, peak at 0.16 s): whip pans and fly-ins"},+ "whoosh.long": {"sound": "whoosh_big/swell", "takes": 2, "align": "peak", "level_db": -6.0,+ "note": "a full air swell for scene transitions (no jet tone, no tail re-rise)"},+ "suck": null,+ "riser": null,+ "drop": {"sound": "pro_sub_drop/quick", "takes": 1, "align": "onset", "level_db": -4.0,+ "note": "the shortest designed sub drop (1.0 s, blooms 110 ms after the cut); set edits.pitch to the film's root (G1-C2)"},+ "key": {"sound": "typing_key/crisp", "takes": 12, "align": "onset", "level_db": -10.0,+ "note": "a crisp mechanical key, a new take per keystroke"},+ "key.space": {"sound": "typing_key/thock", "takes": 4, "align": "onset", "level_db": -9.0,+ "note": "the bigger thocky cap stands in for the space bar"},+ "key.return": {"sound": "typing_key/clicky", "takes": 2, "align": "onset", "level_db": -7.0,+ "note": "a clicky switch for return: brighter and firmer than the run"},+ "click": {"sound": "pro_click/mouse", "takes": 2, "align": "onset", "level_db": -7.0,+ "note": "a mouse-button click (54 ms, 1.1 kHz centroid): the cursor press"},+ "click.confirm": {"sound": "pro_notify/ding_2045", "takes": 1, "align": "onset", "level_db": -9.0,+ "note": "a short clean ding (0.36 s) for a confirmed action"},+ "snap": {"sound": "toggle/latch", "takes": 2, "align": "onset", "level_db": -6.0,+ "note": "press and latch: the designed lock-in (two attacks by design; snap is not a hit role)"},+ "swell": null,+ "bell": {"sound": "pluck/kalimba", "pitches": ["C5", "D5", "E5", "G5", "A5"], "takes": 1, "align": "onset", "level_db": -5.0,+ "note": "the tuned kalimba voice on a C pentatonic: progress steps and motifs"},+ "text": {"sound": "pro_tap/soft", "takes": 3, "align": "onset", "level_db": -12.0,+ "note": "a soft thump when a text fragment resolves, untuned so it never fights the music"}+ },+ "off": {+ "suck": "off by default: a reverse whoosh into a cut stacks a build onto the reveal",+ "riser": "off by default; pro_riser/air_gate is the short opt-in, never a shepard riser",+ "swell": "off by default: a reverse swell before a hit is a stacked lead-in"+ }+}diff --git a/earshot/forge/kits/minimal.json b/earshot/forge/kits/minimal.jsonnew file mode 100644index 0000000..67c870f--- /dev/null+++ b/earshot/forge/kits/minimal.json@@ -0,0 +1,52 @@+{+ "kit": 1,+ "name": "minimal",+ "sr": 48000,+ "note": "Designed, sub-led, effects-only films (no music bed): airy digital ticks, low sub swells for moves, one sub-led hit, the designed sub drop, high-passed key ticks. Every member passes the model-free audit. Riser, swell and suck are off.",+ "roles": {+ "tick": {"sound": "pro_hover_tick/soft", "takes": 3, "align": "onset", "level_db": -10.0,+ "note": "an airy digital tick (32 ms): cursor blinks and counters; the air / glass members click in the audit"},+ "tick.crisp": {"sound": "pro_hover_tick/ping", "takes": 3, "align": "onset", "level_db": -12.0,+ "note": "a short high ping for precise UI ticks"},+ "tock": {"sound": "pro_tap/soft", "takes": 3, "align": "onset", "level_db": -8.0,+ "note": "the soft low thump of a touch"},+ "hit": {"sound": "pro_impact/air", "takes": 2, "align": "onset", "level_db": 0.0,+ "note": "one sub-led gated hit: a single attack, 0.85 s, the weight below 150 Hz; nothing layered on it"},+ "land": {"sound": "pro_pop_in/deep", "takes": 3, "align": "onset", "level_db": -5.0,+ "note": "a low round thump (75 Hz body)"},+ "land.light": {"sound": "pro_tap/finger", "takes": 3, "align": "onset", "level_db": -8.0,+ "note": "a fingertip touch for small elements"},+ "pop": {"sound": "pro_pop_in/round", "takes": 4, "align": "onset", "level_db": -7.0,+ "note": "a round pop-in thump, no pitch glide"},+ "whoosh.short": {"sound": "whoosh_fast/heavy", "takes": 3, "align": "peak", "level_db": -7.0,+ "note": "a darker fast pass (381 Hz centroid) that sits under sub-led sounds"},+ "whoosh.long": {"sound": "pro_whoosh_big/swell", "takes": 2, "align": "peak", "level_db": -5.0,+ "note": "the designed low sub swell into a cut (peak at 0.35 s, almost all energy under 150 Hz)"},+ "suck": null,+ "riser": null,+ "drop": {"sound": "pro_sub_drop/ref", "takes": 1, "align": "onset", "level_db": -3.0,+ "note": "the designed drop that blooms after the cut; set edits.pitch to the film's root (G1-C2)"},+ "key": {"sound": "pro_typing_key/glass", "takes": 12, "align": "onset", "level_db": -12.0,+ "note": "a high-passed designed key tick for kinetic type, a new take per keystroke"},+ "key.space": {"sound": "pro_typing_key/tick", "takes": 4, "align": "onset", "level_db": -12.0,+ "note": "a softer designed tick for spaces"},+ "key.return": {"sound": "pro_typing_key/double", "takes": 2, "align": "onset", "level_db": -10.0,+ "note": "a double tick marks the line end"},+ "click": {"sound": "pro_click/soft", "takes": 2, "align": "onset", "level_db": -9.0,+ "note": "a soft designed UI click (53 ms)"},+ "click.confirm": {"sound": "pro_notify/ding_1822", "takes": 1, "align": "onset", "level_db": -10.0,+ "note": "a short clean ding (0.26 s)"},+ "snap": {"sound": "pro_pop_in/knock", "takes": 2, "align": "onset", "level_db": -6.0,+ "note": "a firm short knock for a lock-in"},+ "swell": null,+ "bell": {"sound": "pro_notify/ding_1822", "pitches": ["F6", "G6", "A6", "C7", "D7"], "takes": 1, "align": "onset", "level_db": -8.0,+ "note": "the clean ding on an F pentatonic around its own pitch (1822 Hz): sparse designed notes, no ringing bell"},+ "text": {"sound": "pro_tap/finger", "takes": 3, "seed": 5200, "align": "onset", "level_db": -13.0,+ "note": "a quiet touch when a text fragment resolves"}+ },+ "off": {+ "suck": "off by default: a reverse whoosh into a cut stacks a build onto the reveal",+ "riser": "off by default; pro_riser/air_gate is the short opt-in, never a shepard riser",+ "swell": "off by default: the sub swell of whoosh.long already carries the move"+ }+}diff --git a/earshot/mcp_server.py b/earshot/mcp_server.pyindex d30d117..47d01a2 100644--- a/earshot/mcp_server.py+++ b/earshot/mcp_server.py@@ -22,6 +22,9 @@ time. Each result is text: the plain-language summary first (plus the listeningcritique text for llm_critique / one row per file for realness on a folder), then compact JSON (always valid JSON;full=true for everything). sheet also returns the picture as an image. A tool whose module is missing from thisinstall answers with a clear message instead of failing the server.++Sound bank tools (no models, pure DSP): sfx_list, sfx_render (one take aimed at the picture), kit_render (a film's+kit.json into takes + kit.lock.json); earshot.forge.sfx / earshot.forge.kit."""from __future__ import annotations@@ -56,6 +59,10 @@ measurements most, verdicts and z next, cosine least. If realness is unavailablechecked; describe's AudioSet synth classes (Sine wave, Beep, Synthesizer) are weaker evidence. The first call thatneeds models takes ~20-60 s; later calls are fast (models stay loaded)."""+INSTRUCTIONS += """+Sounds for a film (no models, fast): sfx_list (the shipped bank) -> sfx_render (one take aimed at a cue: dur, apex,+pitch) or kit_render (a film's kit.json -> takes + kit.lock.json with measured onset / peak / end per take)."""+IMG_INLINE_MAX = 1600 # px, long edge of the inline copy (sent as JPEG q88: ~1/3 of the PNG bytes)JSON_MAX = 7000SILENT_PEAK_DBFS = -70.0 # same near-silence line as describe@@ -523,6 +530,79 @@ TOOLS = [ # (function, read-only, talks to the internet)]+# ------------------------------------------------------------------------------------- the sound bank (no models)+def _out_path(path, what):+ if not path or not isinstance(path, str):+ raise ToolFailure(f'{what}: an absolute path is required')+ return os.path.abspath(os.path.expanduser(path.strip().strip('"')))+++def tool_sfx_list(category: Annotated[str | None, Field(description='only this category, e.g. "whoosh_fast", '+ '"pro_impact", "typing_key", "pluck"')] = None,+ kind: Annotated[str | None, Field(description='only sounds for this cue kind or kit role, e.g. '+ '"whoosh" (short and long), "hit", "key", "bell"')]+ = None,+ full: Full = False) -> str:+ """List earshot's shipped sound bank (no models, instant): every id (<category>/<member>, pluck/<name>,+ fit/<role>/<name>) with its length, onset and peak time, the cue kinds it serves and its knobs (dur; apex for+ the whoosh family; pitch for tonal sounds, with the native note). Use to choose sounds for a film's cues or kit+ before sfx_render / kit_render; filter by category or kind to keep it short."""+ from .forge import sfx++ def run(category=None, kind=None):+ r = sfx.sfx_list(category, kind)+ lines = [r['summary']]+ for x in r['sounds']:+ kn = x['knobs']+ k = [f"dur {kn['dur']}"] + (['apex'] if kn['apex'] else []) + (+ [f"pitch {kn['pitch'].get('note')}"] if kn['pitch'] else [])+ lines.append(f"{x['id']}: {x['dur_s']:.3f} s, peak {x['peak_s']:.3f} s; {','.join(x['kinds']) or '-'}; "+ f"{', '.join(k)}")+ r['text'] = '\n'.join(lines)+ return r+ return _run('sfx_list', dict(category=category, kind=kind), full, run)+++def tool_sfx_render(sound: Annotated[str, Field(description='bank id from sfx_list, e.g. "whoosh_fast/crisp"')],+ out: Annotated[str, Field(description='absolute path of the WAV to write (24-bit)')],+ seed: Annotated[int | None, Field(description="noise seed for a new take (default: the sound's "+ 'own, the delivered final)')] = None,+ dur: Annotated[float | None, Field(description='length in seconds (exact)', gt=0)] = None,+ apex: Annotated[float | None, Field(description='seconds from the start to the loudest moment '+ '(whoosh family)', gt=0)] = None,+ pitch: Annotated[str | None, Field(description='note name ("E5", "Eb6") or Hz ("440"), through '+ "the recipe's own pitch parameter")] = None,+ peak_db: Annotated[float, Field(description='sample peak in dBFS', le=0)] = -1.0,+ full: Full = False) -> str:+ """Render one sound of earshot's shipped bank to a WAV (no models, about a second), aimed at the picture:+ exact dur, the loudest moment on apex (whooshes), a note through the recipe's own pitch parameter (never+ resampled). Returns the measured onset, peak and end (for placing it on a cue) and the model-free audit (clicks,+ truncation, clipping, ring, rising pitch glide). Use for a single cue or to audition a candidate before a kit."""+ from .forge import sfx+ p = _out_path(out, 'out')+ return _run('sfx_render', dict(sound=sound, out=p, seed=seed, dur=dur, apex=apex, pitch=pitch, peak_db=peak_db),+ full, sfx.sfx_render)+++def tool_kit_render(kit: Annotated[str, Field(description="absolute path of the film's kit.json (earshot kit init "+ 'writes one from a preset: calm, crisp, minimal)')],+ out: Annotated[str, Field(description='absolute path of the folder for the takes and '+ 'kit.lock.json')],+ force: Annotated[bool, Field(description='render every take again (default: keep the takes '+ 'whose cache key and file still match)')] = False,+ full: Full = False) -> str:+ """Render a film's sound kit (no models): every role's takes from the bank into WAVs plus kit.lock.json with the+ measured onset, peak, end and loudness of each take, cached by sound, seed, edits and bank version, every take+ audited model-free (a take that fails is re-rolled on a new seed). Use when a film's cues need sounds: the lock+ is what a mixer or cinetic's score.py places on the cue frames."""+ from .forge import kit as _kit+ return _run('kit_render', dict(kit=_file(kit, 'kit'), out=_out_path(out, 'out'), force=force), full,+ _kit.kit_render)+++TOOLS += [(tool_sfx_list, True, False), (tool_sfx_render, False, False), (tool_kit_render, False, False)]++def _sdk():try:from mcp.server.mcpserver import Image, MCPServer as Serverdiff --git a/tests/test_interfaces.py b/tests/test_interfaces.pyindex e68153b..de47abd 100644--- a/tests/test_interfaces.py+++ b/tests/test_interfaces.py@@ -431,7 +431,7 @@ def test_mcp_server_registers_all_tools():tools = anyio.run(srv.list_tools)names = {t.name for t in tools}assert names == {'measure', 'describe', 'match', 'rank', 'find', 'compare', 'ab', 'realness', 'timeline', 'sheet',- 'critique', 'doctor', 'llm_critique'}+ 'critique', 'doctor', 'llm_critique', 'sfx_list', 'sfx_render', 'kit_render'}for t in tools:schema = getattr(t, 'input_schema', None) or t.inputSchemaassert len(t.description) > 120 and 'Use ' in t.description@@ -529,7 +529,7 @@ def test_mcp_stdio_end_to_end(wav, tmp_path):await s.call_tool('rank', {'paths': path + '.missing', 'query': 'a door'}),await s.call_tool('llm_critique', {'path': path}))tools, meas, missing, rank, llm_res = anyio.run(_stdio_session, calls, str(tmp_path / 'server.log'))- assert len(tools.tools) == 13+ assert len(tools.tools) == 16 # 13 listening tools + sfx_list, sfx_render, kit_render (the sound bank)assert not _is_error(meas) and _text(meas).startswith('3.000 s, ') and 'dBTP' in _text(meas)assert _is_error(missing) and 'not found' in _text(missing)assert _is_error(rank) and 'no audio/video files found' in _text(rank) # a plain string passes the schemadiff --git a/tests/test_sfx_kit.py b/tests/test_sfx_kit.pynew file mode 100644index 0000000..d567730--- /dev/null+++ b/tests/test_sfx_kit.py@@ -0,0 +1,212 @@+"""earshot sfx (the model-free audit and the CLI) and earshot kit (presets, render + lock + cache, check, audition),+plus the MCP tool functions of the sound bank. Synthetic signals and short bank sounds only; no models."""+import json+import os++import numpy as np+import pytest+import soundfile as sf++from earshot import cli, mcp_server+from earshot.forge import bank, kit, sfx++SR = 48000+rng = np.random.RandomState(7)+++def _sweep(f0, f1, dur=0.35):+ t = np.arange(int(dur * SR)) / SR+ f = f0 * (f1 / f0) ** (t / dur)+ return (0.5 * np.sin(2 * np.pi * np.cumsum(f) / SR) * np.hanning(len(t)) ** 0.3).astype(np.float32)+++def _burst(t0, tau=0.06, dur=0.8):+ t = np.arange(int(dur * SR)) / SR+ y = np.zeros_like(t)+ on = t >= t0+ y[on] = rng.randn(on.sum()) * np.exp(-(t[on] - t0) / tau)+ y[:int(t0 * SR) + 1] = 0.0+ return y / np.abs(y).max() # peak 1: callers scale it under full scale+++def _codes(c, key='warnings'):+ return {w['code'] for w in c[key]}+++# ----------------------------------------------------------------------------------------------------- the audit+def test_rising_glide_is_flagged_and_falling_or_steady_is_not():+ up = sfx.check(_sweep(400, 1200))+ assert 'rising_glide' in _codes(up) and not up['ok'] and up['glide']['rise_st'] > 15+ down = sfx.check(_sweep(1200, 400))+ assert 'rising_glide' not in _codes(down) and down['glide']['rise_st'] < 1+ small = sfx.check(_sweep(500, 500 * 2 ** (3 / 12))) # 3 semitones: a natural inflection+ assert 'rising_glide' not in _codes(small)+ t = np.arange(SR) / SR+ bell = sfx.check((0.5 * np.sin(2 * np.pi * 880 * t) * np.exp(-t / 0.2)).astype(np.float32))+ assert bell['glide']['rise_st'] < 1 and 'rising_glide' not in _codes(bell)+ noise = sfx.check((_burst(0.01, 0.1) * 0.5).astype(np.float32))+ assert noise['glide']['tonal_share'] < 0.2 and 'rising_glide' not in _codes(noise)+++def test_stacked_hit_and_pre_swell_are_warnings_for_a_hit_role():+ double = (0.4 * (_burst(0.01) + _burst(0.13))).astype(np.float32)+ assert 'stacked' in _codes(sfx.check(double, role='hit'))+ assert 'stacked' not in _codes(sfx.check(double)) | _codes(sfx.check(double), 'notes') # no context: silent+ assert 'stacked' in _codes(sfx.check(double, category='impact'), 'notes') # a hit category: a note+ one = (0.4 * _burst(0.01)).astype(np.float32)+ c = sfx.check(one, role='hit')+ assert c['layers']['count'] == 1 and c['ok'], c['summary']+ t = np.arange(int(0.8 * SR)) / SR+ lead = np.where(t < 0.25, (t / 0.25) ** 3 * 0.3 * rng.randn(len(t)), 0.0) + _burst(0.25)+ assert 'pre_swell' in _codes(sfx.check((0.4 * lead / np.abs(lead).max()).astype(np.float32), role='hit'))+++def test_artifacts_are_flagged():+ t = np.arange(int(0.3 * SR)) / SR+ tone = 0.5 * np.sin(2 * np.pi * 440 * t) * np.exp(-t / 0.05)+ assert sfx.check(tone.astype(np.float32))['ok']+ spike = tone.copy()+ spike[int(0.15 * SR)] += 0.3 # a one-sample spike inside the decay+ assert 'clicks' in _codes(sfx.check(spike.astype(np.float32)))+ clip = np.clip(3 * np.sin(2 * np.pi * 440 * t), -1, 1) * np.hanning(len(t))+ clip = np.clip(clip * 1.5, -0.9, 0.9)+ assert 'clipping' in _codes(sfx.check(clip.astype(np.float32)))+ assert 'edge' in _codes(sfx.check((0.5 * np.ones(4800)).astype(np.float32)))+ cut = (0.5 * rng.randn(int(0.5 * SR)) * np.exp(-np.arange(int(0.5 * SR)) / (0.3 * SR)))[:int(0.15 * SR)]+ cut[-24:] *= np.linspace(1, 0, 24)+ assert 'truncated' in _codes(sfx.check(cut.astype(np.float32)))+ assert 'truncated' in _codes(sfx.check(cut.astype(np.float32), category='riser'), 'notes') # the design+++# --------------------------------------------------------------------------------------------------------- kits+def test_presets_are_valid_restrained_and_explained():+ assert kit.presets() == ['calm', 'crisp', 'minimal']+ for name in kit.presets():+ k = kit.preset(name)+ assert kit.problems(k) == [], name+ assert set(k['roles']) == set(kit.ROLES), (name, set(kit.ROLES) ^ set(k['roles']))+ for r in kit.RESTRAINED:+ assert k['roles'][r] is None and k['off'][r], (name, r)+ for role, spec in k['roles'].items():+ if spec is None:+ assert role in k['off'], (name, role)+ continue+ assert len(spec['note']) > 20, (name, role)+ cat = spec['sound'].split('/')[0]+ assert spec['sound'] not in kit.NEVER and cat not in kit.NEVER_CATEGORIES, (name, role)+ hits = [s['sound'] for r, s in k['roles'].items() if s and r == 'hit']+ assert len(hits) == 1+ files = [t['file'] for t in kit.plan(k)]+ assert len(files) == len(set(files))+++def _tiny(**edit):+ k = {'kit': 1, 'name': 'tiny', 'sr': 48000,+ 'roles': {'tick': {'sound': 'tap/finger', 'takes': 2, 'level_db': -6.0},+ 'bell': {'sound': 'pro_notify/ding_1822', 'pitches': ['A6', 'C7']},+ 'whoosh.short': {'sound': 'whoosh_fast/tight', 'edits': {'dur': 0.5, 'apex': 0.2}},+ 'riser': None}}+ for role, spec in edit.items():+ k['roles'][role] = spec+ return k+++def test_kit_render_lock_and_cache(tmp_path):+ out = tmp_path / 'kit'+ lock = kit.render(_tiny(), str(out))+ assert lock['stats']['rendered'] == 5 and lock['stats']['cached'] == 0+ disk = json.loads((out / 'kit.lock.json').read_text(encoding='utf-8'))+ assert disk['kit'] == 1 and disk['bank'] == bank.VERSION and disk['sr'] == 48000 and disk['roles']['riser'] is None+ tick = disk['roles']['tick']+ assert tick['sound'] == 'tap/finger' and tick['align'] == 'onset' and tick['level_db'] == -6.0+ assert [t['file'] for t in tick['takes']] == ['tick_1.wav', 'tick_2.wav']+ e = bank.get('tap/finger')+ assert [t['seed'] for t in tick['takes']][0] in (e['seed'], e['seed'] + 1000)+ for t in tick['takes']:+ for k in ('file', 'seed', 'pitch', 'onset_s', 'peak_s', 'end_s', 'dur_s', 'peak_db', 'lufs_m_max', 'sha1'):+ assert k in t+ y, fs = sf.read(str(out / t['file']))+ assert fs == 48000 and abs(len(y) / fs - t['dur_s']) < 1e-3+ assert [t['file'] for t in disk['roles']['bell']['takes']] == ['bell_A6.wav', 'bell_C7.wav']+ w = disk['roles']['whoosh.short']+ assert w['align'] == 'peak' and abs(w['takes'][0]['peak_s'] - 0.2) <= 0.005 and w['takes'][0]['dur_s'] == 0.5+ again = kit.render(_tiny(), str(out))+ assert again['stats']['rendered'] == 0 and again['stats']['cached'] == 5+ moved = kit.render(_tiny(tick={'sound': 'tap/finger', 'takes': 2, 'edits': {'dur': 0.1}}), str(out))+ assert moved['stats']['rendered'] == 2 and moved['stats']['cached'] == 3+ fewer = kit.render(_tiny(bell=None), str(out))+ assert fewer['stats']['removed'] == 2 and not (out / 'bell_A6.wav').exists()+ forced = kit.render(_tiny(bell=None), str(out), force=True)+ assert forced['stats']['rendered'] == 3+++def test_kit_check_and_problems(tmp_path):+ k = _tiny()+ assert kit.check(k)['ok']+ bad = _tiny(tick={'sound': 'tap/fingr', 'takes': 0, 'edits': {'speed': 2}})+ probs = kit.problems(bad)+ assert any('tap/finger' in p for p in probs) and any('takes' in p for p in probs)+ assert any('edits' in p for p in probs)+ r = kit.check(bad)+ assert not r['ok'] and r['problems']+ loud = _tiny(riser={'sound': 'pro_zip/up'})+ r = kit.check(loud)+ assert not r['ok'] and any('rising_glide' in {w['code'] for w in row['warnings']} for row in r['roles']['riser'])+ assert any('riser is sounded' in n for n in r['notes']) and any('synth whip' in n for n in r['notes'])+ with pytest.raises(kit.KitError, match='unknown sound'):+ kit.load(bad)+++def test_kit_audition(tmp_path):+ r = kit.audition(_tiny(), str(tmp_path / 'aud.wav'), takes=str(tmp_path / 'takes'))+ y, fs = sf.read(str(tmp_path / 'aud.wav'))+ assert fs == 48000 and y.ndim == 2 and len(r['index']) == 5 and r['index'][0]['role'] == 'tick'+ assert np.abs(y).max() <= 10 ** (-1 / 20) + 1e-4 and (tmp_path / 'aud.txt').is_file()+++# ---------------------------------------------------------------------------------------------- CLI and the API+def test_cli_sfx(tmp_path, capsys, wav):+ assert cli.main(['sfx', 'list', '--kind', 'hit', '--json']) == 0+ rows = json.loads(capsys.readouterr().out)['sounds']+ assert rows and all(any(k.split('.')[0] == 'hit' for k in r['kinds']) for r in rows)+ f = str(tmp_path / 't.wav')+ assert cli.main(['sfx', 'render', 'tap/finger', '-o', f, '--dur', '0.1', '--seed', '3']) == 0+ assert 'wrote' in capsys.readouterr().out and abs(sf.info(f).duration - 0.1) < 1e-4+ assert cli.main(['sfx', 'check', f]) == 0+ assert 'clean' in capsys.readouterr().out+ assert cli.main(['sfx', 'check', wav(_sweep(300, 1500))]) == 1+ assert 'semitones' in capsys.readouterr().out+ assert cli.main(['sfx', 'render', 'whoosh_fast/crisp', '-o', f, '--pitch', 'C5']) == 1 # a readable error+ assert 'noise pass-by' in capsys.readouterr().err+++def test_cli_kit(tmp_path, capsys):+ k = str(tmp_path / 'audio' / 'kit.json')+ assert cli.main(['kit', 'init', '--preset', 'minimal', '-o', k]) == 0+ assert json.loads(open(k, encoding='utf-8').read())['name'] == 'minimal'+ assert cli.main(['kit', 'init', '--preset', 'minimal', '-o', k]) == 1 # exists: no overwrite+ capsys.readouterr()+ small = str(tmp_path / 'small.json')+ with open(small, 'w', encoding='utf-8') as fh:+ json.dump(_tiny(bell=None, **{'whoosh.short': None}), fh)+ assert cli.main(['kit', 'render', small, '--out', str(tmp_path / 'takes'), '--json']) == 0+ r = json.loads(capsys.readouterr().out)+ assert r['stats']['takes'] == 2 and os.path.isfile(r['file'])+ assert cli.main(['kit', 'check', small, '--out', str(tmp_path / 'takes')]) == 0+ assert '2 / 2 takes clean' in capsys.readouterr().out+++def test_api_and_mcp_tools(tmp_path):+ from earshot import api+ assert api.sfx_list(category='pluck')['sounds'][0]['id'] == 'pluck/kalimba'+ text = mcp_server.tool_sfx_list(kind='bell')+ assert 'sounds in the bank' in text.split('\n')[0] and 'pluck/kalimba' in text+ f = str(tmp_path / 'mcp.wav')+ text = mcp_server.tool_sfx_render('tap/finger', f, dur=0.12)+ assert os.path.isfile(f) and 'onset' in text+ with pytest.raises(mcp_server.ToolFailure, match='unknown sound id'):+ mcp_server.tool_sfx_render('tap/fingr', f)+ k = tmp_path / 'k.json'+ k.write_text(json.dumps(_tiny(bell=None, **{'whoosh.short': None})), encoding='utf-8')+ text = mcp_server.tool_kit_render(str(k), str(tmp_path / 'takes'))+ assert '2 takes' in text and (tmp_path / 'takes' / 'kit.lock.json').is_file()