Skip to content

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.py
index 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.py
index 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.py
new file mode 100644
index 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 p
diff --git a/earshot/forge/kits/calm.json b/earshot/forge/kits/calm.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.py
index 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 listening
critique 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 this
install 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 unavailable
checked; describe's AudioSet synth classes (Sine wave, Beep, Synthesizer) are weaker evidence. The first call that
needs 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 = 7000
SILENT_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 Server
diff --git a/tests/test_interfaces.py b/tests/test_interfaces.py
index 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.inputSchema
assert 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 schema
diff --git a/tests/test_sfx_kit.py b/tests/test_sfx_kit.py
new file mode 100644
index 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()