Ears for coding agents: let AI hear, review and make sound. CPU-only, open source.
"""The fit engine (earshot/forge/fit: auto, quality, codegen, CLI): synthetic signals of known structure only."""
import json
import numpy as np
import pytest
from earshot.forge import dsp
from earshot.forge.fit import auto, codegen
from earshot.forge.fit import quality as Q
SR = 48000
def struck(f=(1200.0, 2900.0), tau=(0.03, 0.012), amp=(0.6, 0.3), n_s=0.15, t0=0.01, seed=0, noise=0.02):
"""a click: damped modes from t0 plus a short decaying noise burst and a faint floor"""
r = np.random.default_rng(seed)
n = int(n_s * SR)
t = np.arange(n) / SR - t0
on = t >= 0
y = np.zeros(n)
for fi, ti, ai in zip(f, tau, amp):
y += on * ai * np.exp(-np.clip(t, 0, None) / ti) * np.sin(2 * np.pi * fi * np.clip(t, 0, None))
y += on * noise * 10 * r.standard_normal(n) * np.exp(-np.clip(t, 0, None) / 0.004)
y += 1e-4 * r.standard_normal(n)
return y
def swell(n_s=0.5, seed=1):
"""a noise gesture: band-limited noise swelling over 300 ms, then fading"""
r = np.random.default_rng(seed)
n = int(n_s * SR)
t = np.arange(n) / SR
env = np.minimum(t / 0.3, 1.0) ** 2 * np.exp(-np.clip(t - 0.3, 0, None) / 0.05)
return 0.3 * dsp.butter(r.standard_normal(n), 'band', (800.0, 5000.0)) * env
def tone(f=(660.0, 1320.0), n_s=1.2, decay=0.4):
t = np.arange(int(n_s * SR)) / SR
y = sum(a * np.sin(2 * np.pi * fi * t) for fi, a in zip(f, (0.5, 0.2)))
return y * np.exp(-t / decay) * np.minimum(t / 0.003, 1.0)
def chirp(n_s=0.2, f0=400.0, f1=1400.0):
t = np.arange(int(n_s * SR)) / SR
f = f0 * (f1 / f0) ** (t / n_s)
ph = 2 * np.pi * np.cumsum(f) / SR
return 0.5 * np.sin(ph) * np.minimum(t / 0.002, 1.0) * np.exp(-t / 0.08)
# --------------------------------------------------------------------------------------------------- quality
def test_quality_identity_gain_and_shift():
x = struck()
q = Q.quality(x, x)
assert q['mel_db'] == 0 and q['tone_db'] == 0 and q['onset_err'] == 0 and q['env_corr'] > 0.999
q2 = Q.quality(x, 0.5 * x) # each sound is levelled: only level_db sees a gain
assert abs(q2['level_db'] + 6.02) < 0.05 and q2['mel_db'] < 1e-6
q3 = Q.quality(x, np.roll(x, int(0.03 * SR))) # a timing error counts (no re-alignment on the resynthesis)
assert q3['mel_db'] > 5 and q3['env_corr'] < q['env_corr']
assert Q.score(q) < Q.score(q3)
def test_quality_onset_sharpness_and_tone():
x = struck()
t = np.arange(len(x)) / SR - 0.01
soft = Q.quality(x, x * np.clip(t / 0.004, 0, 1))['onset_err'] # a 4 ms fade-in over the strike
softer = Q.quality(x, x * np.clip(t / 0.012, 0, 1))['onset_err'] # a 12 ms one
assert Q.quality(x, x.copy())['onset_err'] < 0.05 and 0.4 < soft < softer and softer > 1.0
dark = dsp.butter(x, 'low', 1500.0)
assert Q.quality(x, dark)['tone_db'] > 3
# --------------------------------------------------------------------------------------------------- character
@pytest.mark.parametrize('sig,cls,first', [
(struck(), 'struck', 'modal'),
(swell(), 'gesture', 'spectral'),
(tone(), 'ringing', 'sines'),
(chirp(), 'glide', 'sines'),
])
def test_character_classes(sig, cls, first):
c = auto.character(sig)
assert c['class'] == cls, c
p = auto.plan(c)
assert p[0] == first
assert len(p) == len(set(p))
if c['dur_s'] < 1.0:
assert set(p) == set(auto.ALL) # short sounds: every candidate is cheap enough to try
# --------------------------------------------------------------------------------------------------- fitting
def test_auto_picks_by_quality_and_post_stage():
x = struck()
got = {}
m = auto.fit(x, candidates=['modal', 'spectral'], fast=True, collect=got)
fe = m['fit_engine']
assert fe['kind'] == 'auto' and set(got) == {'modal', 'spectral'}
sc = {r['candidate']: r['score'] for r in fe['candidates']}
assert fe['chosen'] == min(sc, key=sc.get) == 'modal'
assert set(m['post']) >= {'eq_db', 'gain_db', 'pre'} and len(m['post']['eq_db']) == 28
y = auto.render(m, seed=0)
assert len(y) == len(x)
q = Q.quality(x, y)
assert q['mel_db'] < 6 and q['env_corr'] > 0.85 and abs(q['level_db']) < 1.5
assert np.array_equal(auto.render(m, seed=3), auto.render(m, seed=3)) # deterministic per seed
def test_post_stage_cleans_the_pre_onset_and_matches_balance():
x = struck(t0=0.02)
r = np.random.default_rng(5)
leak = x + 0.05 * r.standard_normal(len(x)) * (np.arange(len(x)) < int(0.02 * SR)) # noise before the strike
leak = dsp.butter(leak, 'low', 6000.0) # and a darker balance
post = auto.fit_post(x, [leak])
y = auto.apply_post(leak, post)
n_on = int(0.019 * SR)
p = lambda v: 10 * np.log10(np.mean(v[:n_on] ** 2) + 1e-20)
assert p(y) < p(leak) - 15 # pre-onset leak removed
assert Q.quality(x, y)['tone_db'] < Q.quality(x, leak)['tone_db']
def test_hybrid_layers_and_deterministic_part():
x = struck(noise=0.05)
m = auto.fit_hybrid(x, ('modal', 'spectral'), fast=True)
assert m['kind'] == 'hybrid' and [L['role'] for L in m['layers']] == ['body', 'air']
det = m['layers'][0]['model']
assert det['layer'] == 'deterministic' and 'post' not in det
assert all(max(v for _, v in env) <= -200 for env in det['noise']['env']) # no noise in the deterministic layer
y = auto.render(m, seed=1)
assert y.shape[0] == len(x) and Q.quality(x, y)['mel_db'] < 7
y2 = auto.render(m, seed=1, body_db=-60.0) # the air layer alone is quieter
assert np.sqrt(np.mean(y2 ** 2)) < np.sqrt(np.mean(y ** 2))
with pytest.raises(ValueError):
auto.fit_hybrid(x, ('spectral', 'sines'))
def test_render_rejects_unknown_knobs():
m = auto.fit(struck(), kind='modal', fast=True)
with pytest.raises(ValueError):
auto.render(m, seed=0, transpose=2)
assert len(auto.render(m, seed=0, size=1.2, vary=0.3)) > 0
# --------------------------------------------------------------------------------------------------- codegen
def test_codegen_recipe_round_trip(tmp_path):
x = struck()
m = auto.fit(x, kind='modal', fast=True)
src = codegen.to_recipe(m, name='synth_click', target='a short test click')
assert 'fit_engine' not in src.split('MODEL = ', 1)[1]
ns = {}
exec(codegen.literal(m), ns)
assert ns['MODEL'] == {k: v for k, v in m.items() if k != 'fit_engine'} # the literal is exact
p = codegen.write_recipe(str(tmp_path / 'synth_click.py'), m, target='a short test click')
rec = codegen.load_recipe(p)
assert rec.TARGET == 'a short test click' and rec.KIND == 'modal'
assert set(rec.SPACE) == set(rec.DEFAULTS) == set(auto.KNOBS['modal'])
for spec in rec.SPACE.values(): # valid forge SPACE specs
assert len(spec) in (2, 3) and spec[0] < spec[1]
assert np.array_equal(rec.render_seed(0), auto.render(m, seed=0)) # the code renders the fit, bitwise
seed = int(dsp.rng(7).integers(0, 2 ** 31 - 1))
assert np.array_equal(rec.render(rec.DEFAULTS, dsp.rng(7)), auto.render(m, seed=seed))
var = rec.render(dict(rec.DEFAULTS, size=1.2, vary=0.4), dsp.rng(7))
assert len(var) > 0 and not np.allclose(var[:len(x)], rec.render_seed(0)[:len(var)])
def test_codegen_sines_and_spectral_recipes(tmp_path):
for sig, kind in ((tone(n_s=0.5, decay=0.15), 'sines'), (swell(), 'spectral')):
m = auto.fit(sig, kind=kind, fast=True)
rec = codegen.load_recipe(codegen.write_recipe(str(tmp_path / f'r_{kind}.py'), m))
assert np.array_equal(rec.render_seed(2), auto.render(m, seed=2))
assert set(rec.SPACE) == set(auto.KNOBS[kind])
# --------------------------------------------------------------------------------------------------- morph
def _strongest_mode(m):
md = np.array(m['strikes'][0]['modes'])
return md[np.argmax(md[:, 2] ** 2 * md[:, 1]), 0]
def test_morph_modal_interpolates_frequency_and_keeps_endpoints():
a = auto.fit(struck(f=(1000.0,), tau=(0.04,), amp=(0.6,), noise=0.002), kind='modal', fast=True)
b = auto.fit(struck(f=(1600.0,), tau=(0.04,), amp=(0.6,), noise=0.002, seed=3), kind='modal', fast=True)
mid = auto.morph(a, b, 0.5)
assert abs(_strongest_mode(mid) / np.sqrt(1000.0 * 1600.0) - 1) < 0.03
assert np.allclose(auto.render(auto.morph(a, b, 0.0), 1), auto.render(a, 1), atol=1e-9)
assert np.allclose(auto.render(auto.morph(a, b, 1.0), 1), auto.render(b, 1), atol=1e-9)
mm = auto.morph_model(a, b, 0.3)
assert 'morph' in auto.knobs_of(mm)
assert np.array_equal(auto.render(mm, 2), auto.render(auto.morph(a, b, 0.3), 2))
assert np.array_equal(auto.render(mm, 2, morph=0.5), auto.render(mid, 2))
s = auto.fit(swell(), kind='spectral', fast=True)
with pytest.raises(ValueError):
auto.morph(a, s, 0.5)
def test_morph_sines_and_spectral():
from earshot.forge.fit.sines import partial_freq
a = auto.fit(tone(f=(440.0, 880.0), n_s=0.4, decay=0.15), kind='sines', fast=True)
b = auto.fit(tone(f=(660.0, 1320.0), n_s=0.4, decay=0.15), kind='sines', fast=True)
mid = auto.morph(a, b, 0.5)
f0 = partial_freq(mid['partials'][0])
assert abs(f0 / np.sqrt(440.0 * 660.0) - 1) < 0.03
assert len(auto.render(mid, 0)) > 0
r = np.random.default_rng(2)
lo = auto.fit(0.2 * dsp.butter(r.standard_normal(SR // 3), 'low', 1000.0), kind='spectral', fast=True)
hi = auto.fit(0.2 * dsp.butter(r.standard_normal(SR // 3), 'high', 4000.0), kind='spectral', fast=True)
cen = lambda y: float(np.sum(np.abs(np.fft.rfft(Q.mono(y))) ** 2 * np.fft.rfftfreq(len(Q.mono(y)), 1 / SR))
/ np.sum(np.abs(np.fft.rfft(Q.mono(y))) ** 2))
c_lo, c_mid, c_hi = (cen(auto.render(m, 0)) for m in (lo, auto.morph(lo, hi, 0.5), hi))
assert c_lo < c_mid < c_hi
# --------------------------------------------------------------------------------------------------- CLI
def test_cli_fit_and_morph(tmp_path, wav):
from earshot.cli import main
a = wav(struck(), 'a.wav')
b = wav(struck(f=(1500.0, 3600.0), seed=4), 'b.wav')
out = tmp_path / 'made' / 'a_fit.py'
assert main(['fit', a, '-o', str(out), '--kind', 'modal', '--fast', '--quiet', '--json',
'--out', str(tmp_path / 'r.json')]) == 0
r = json.load(open(tmp_path / 'r.json'))
for k in ('recipe', 'wav', 'png', 'model'):
assert (tmp_path / 'made').joinpath(r['files'][k].rsplit('/', 1)[-1]).exists()
assert r['code_renders_fit'] is True and r['quality']['mel_db'] < 6
assert main(['fit', '--morph', a, b, '--amount', '0.4', '-o', str(tmp_path / 'ab.py'), '--fast', '--quiet']) == 0
rec = codegen.load_recipe(str(tmp_path / 'ab.py'))
assert 'morph' in rec.SPACE and rec.DEFAULTS['morph'] == 0.4
assert len(rec.render(rec.DEFAULTS, dsp.rng(0))) > 0
@pytest.mark.slow
def test_fitted_recipe_runs_in_the_forge(tmp_path):
from earshot.forge import forge
m = auto.fit(struck(), kind='modal', fast=True)
rec = codegen.load_recipe(codegen.write_recipe(str(tmp_path / 'f.py'), m, target='a short plastic click'))
r = forge(rec, refs=None, budget=8, pop=4, keep=1, seed=0, out=None, log=lambda *a: None)
assert r['picks'] and set(r['picks'][0]['params']) >= set(rec.SPACE)