Ears for coding agents: let AI hear, review and make sound. CPU-only, open source.
"""earshot.forge.fit.gesture (tones + air) and the spectral additions it rides on (detail fit, trajectory, motion
knobs, the ridge cache): known structure recovered from synthetic signals, render knobs, determinism, serialisation."""
import json
import numpy as np
import pytest
from earshot.forge.fit import gesture as G
from earshot.forge.fit import spectral as sp
SR = 48000
def _band(x, lo, hi):
X = np.fft.rfft(x)
f = np.fft.rfftfreq(len(x), 1 / SR)
X[(f < lo) | (f > hi)] = 0
return np.fft.irfft(X, len(x))
def _whoosh(n_s=0.7, seed=0, tone=True, stereo=True):
"""band noise swelling to a peak at 0.3 s, a gliding tone (1.5 -> 3 kHz) over it; the right channel quieter"""
rng = np.random.default_rng(seed)
n = int(n_s * SR)
t = np.arange(n) / SR
env = np.clip(t / 0.3, 0, 1) ** 2 * np.exp(-np.maximum(t - 0.3, 0) / 0.1)
x = 0.1 * _band(rng.standard_normal(n), 300, 12000) * env
if tone:
f = 1500 * 2 ** (t / t[-1])
fade = np.clip(t / 0.2, 0, 1) * np.clip((n_s - 0.05 - t) / 0.1, 0, 1)
x = x + 0.05 * np.sin(2 * np.pi * np.cumsum(f) / SR) * fade
return np.stack([x, 0.6 * x], 1) if stereo else x
def _balance_db(x, y, within_db=40.0):
"""RMS third-octave balance difference over the bands within within_db of x's loudest (the synthetic sources are
brick-wall band-limited: a band 50 dB under the rest, empty in x, would rule an unweighted RMS)"""
from earshot.forge.tone import profile
px, py = profile(x.mean(1) if x.ndim == 2 else x), profile(y.mean(1) if y.ndim == 2 else y)
sel = px > px.max() - within_db
return float(np.sqrt(np.mean((px[sel] - py[sel]) ** 2)))
def _band_db(y, lo, hi):
m = y.mean(1) if y.ndim == 2 else y
P = np.abs(np.fft.rfft(m)) ** 2
f = np.fft.rfftfreq(len(m), 1 / SR)
return 10 * np.log10(P[(f >= lo) & (f < hi)].sum() + 1e-30)
def test_residual_takes_a_tone_out_and_leaves_the_rest():
rng = np.random.default_rng(1)
n = SR // 2
t = np.arange(n) / SR
noise = 0.05 * _band(rng.standard_normal(n), 200, 12000)
tone = 0.2 * np.sin(2 * np.pi * 2000 * t)
r = G.residual(noise + tone, tone)
assert _band_db(noise + tone, 1950, 2050) - _band_db(r, 1950, 2050) > 12 # the tone is gone
assert abs(_band_db(r, 4000, 10000) - _band_db(noise, 4000, 10000)) < 0.5 # the noise stays
assert np.abs(G.residual(noise, noise)).max() < 1e-9 # nothing left of itself
assert np.allclose(G.residual(noise, np.zeros(n)), noise, atol=1e-9) # a silent Y changes nothing
# never adds what Y has and X has not (a waveform subtraction would)
assert _band_db(G.residual(noise, tone), 1950, 2050) <= _band_db(noise, 1950, 2050) + 0.01
def test_gesture_fit_splits_tones_and_air():
x = _whoosh()
m = G.fit(x, fast=True)
assert m['kind'] == G.KIND and m['channels'] == 2
assert m['tones'] is not None and m['fit']['tone_share'] > 0.2
assert m['air']['kind'] == sp.KIND and m['air']['stereo'] is not None
tr = m['traj']
assert abs(tr['peak_s'] - 0.3) < 0.05 and tr['rise_s'] > 0.1
assert np.median(tr['pan_db']) == pytest.approx(10 * np.log10(1 / 0.36), abs=1.5) # L 4.4 dB over R
y = G.render(m, seed=0)
assert y.shape == x.shape
q = sp.compare(x, y)
assert q['env_corr'] > 0.9 and _balance_db(x, y) < 2.0
# the tones keep the glide: the 1.5-3 kHz band holds the render's tonal energy like the original's
assert abs(_band_db(y, 1400, 3200) - _band_db(x, 1400, 3200)) < 2.0
def test_air_only_and_tone_floor():
x = _whoosh(tone=False, seed=2)
m = G.fit(x, fast=True)
assert m['tones'] is None or m['fit']['tone_share'] < 0.5
m0 = G.fit(x, fast=True, tones=False)
assert m0['tones'] is None and m0['fit']['partials'] == 0
m1 = G.fit(x, fast=True, tone_min=1.1) # a floor nothing reaches: air only
assert m1['tones'] is None
assert G.render(m0, seed=1).shape == x.shape
def test_render_determinism_fresh_air_and_json(tmp_path):
m = G.fit(_whoosh(seed=3), fast=True, name='synthetic')
p = tmp_path / 'g.json'
G.save(m, str(p))
m2 = G.load(str(p))
assert json.loads(json.dumps(m)) == m2
a, b = G.render(m, seed=5), G.render(m2, seed=5)
assert np.array_equal(a, b)
c = G.render(m, seed=6)
d = a - c # the tones are the same, the air is new noise
assert 0.05 < np.sqrt((d ** 2).mean() / (a ** 2).mean()) < 1.5
assert G.summary(m).startswith('synthetic:')
with pytest.raises(ValueError):
G.render({'kind': 'sines', 'version': 1})
def test_render_knobs():
m = G.fit(_whoosh(seed=4), fast=True)
base = G.render(m, seed=1)
assert len(G.render(m, seed=1, length=1.5)) == pytest.approx(1.5 * len(base), abs=4)
assert np.abs(G.render(m, seed=1, gain_db=-6.0)).max() < np.abs(base).max()
quiet_air = G.render(m, seed=1, air_db=-20.0)
assert _band_db(quiet_air, 8000, 12000) < _band_db(base, 8000, 12000) - 6 # the air carries the highs
mono = G.render(m, seed=1, stereo=False)
assert mono.ndim == 1
take = G.render(m, seed=2, vary=0.3, ring=True)
assert len(take) >= len(base) and np.abs(take[-8:]).max() < 1e-3 * np.abs(take).max() + 1e-9 # faded end
# motion: a pass-by pan moves the energy from the left channel to the right
y = G.render(m, seed=1, motion=0.8, pan=0.0)
h = int(m['traj']['peak_s'] * SR)
lr = lambda s: 10 * np.log10((s[:, 0] ** 2).sum() / (s[:, 1] ** 2).sum())
assert lr(y[:h]) > lr(y[h:]) + 3
def test_bend_is_a_doppler_pitch_turn():
n = SR // 2
t = np.arange(n) / SR
y = np.sin(2 * np.pi * 1000 * t)
b = sp.bend(y, 0.25, 0.03, 2.0)
def freq(s):
z = np.nonzero(np.diff(np.signbit(s)))[0]
return 0.5 * SR / np.mean(np.diff(z))
early, late = freq(b[int(0.05 * SR):int(0.15 * SR)]), freq(b[int(0.35 * SR):int(0.45 * SR)])
assert early == pytest.approx(1000 * 2 ** (2 / 12), rel=0.02)
assert late == pytest.approx(1000 * 2 ** (-2 / 12), rel=0.02)
assert len(b) > n # the receding tail is read out more slowly
assert sp.bend(y, 0.25, 0.03, 0.0) is not None and np.array_equal(sp.bend(y, 0.25, 0.03, 0.0), y)
def test_spectral_detail_fit_keeps_a_stutter_gate():
rng = np.random.default_rng(5)
n = int(0.6 * SR)
t = np.arange(n) / SR
gate = (np.floor(t / 0.04) % 2 == 0).astype(float) # 40 ms on, 40 ms off
x = 0.1 * _band(rng.standard_normal(n), 300, 12000) * gate
lv = lambda m: sp._db((10 ** (np.asarray(m['env']['db']) / 10) * sp.bandwidths(sp.centers())).sum(1))
smooth = sp.fit(x, texture=False, ridges=False)
detail = sp.fit(x, texture=False, ridges=False, **{k: v for k, v in sp.DETAIL.items() if k != 'max_ridges'})
assert detail['fit']['rank'] == 0
assert np.ptp(lv(detail)) > np.ptp(lv(smooth)) + 6 # the gaps stay deep
q = sp.compare(x, sp.render(detail, seed=1))
assert q['env_corr'] > sp.compare(x, sp.render(smooth, seed=1))['env_corr']
def test_trajectory_reads_sweep_pan_and_width():
rng = np.random.default_rng(6)
n = int(0.8 * SR)
t = np.arange(n) / SR
lo = _band(rng.standard_normal(n), 300, 1200) * np.clip(1 - t / 0.8, 0, 1)
hi = _band(rng.standard_normal(n), 3000, 9000) * np.clip(t / 0.8, 0, 1)
x = 0.1 * (lo + hi)
m = sp.fit(np.stack([x, 0.5 * x], 1), texture=False, ridges=False)
tr = sp.trajectory(m)
c = np.asarray(tr['centroid_hz'])
assert c[-1] > 2 * c[0] # an upward sweep
assert np.median(tr['pan_db']) == pytest.approx(6.0, abs=1.0)
assert np.median(tr['width']) < 0.05 # fully correlated
y = sp.render(m, seed=2)
assert np.array_equal(y, sp.render(m, seed=2, doppler=0.0, proximity=0.0, pan=1.0, motion=0.0))
far = sp.render(m, seed=2, proximity=1.0)
k = int(0.1 * SR) # the start sits under the peak: duller when far
dull = lambda s: _band_db(s[:k], 300, 1200) - _band_db(s[:k], 3000, 9000)
assert dull(far) > dull(y)
flat = sp.render(m, seed=2, pan=0.0).astype(np.float64)
assert abs(10 * np.log10((flat[:, 0] ** 2).sum() / (flat[:, 1] ** 2).sum())) < 1.0
def test_trajectory_tilt_reads_the_slope_where_the_energy_is():
rng = np.random.default_rng(8)
n = int(0.8 * SR)
t = np.arange(n) / SR
P = np.fft.rfft(rng.standard_normal(n))
f = np.fft.rfftfreq(n, 1 / SR)
P[1:] /= np.sqrt(f[1:] / 1000.0)
P[0] = 0
pink = np.fft.irfft(P, n)
x = 0.05 * (pink * np.clip(1 - t / 0.8, 0, 1) + 0.3 * rng.standard_normal(n) * np.clip(t / 0.8, 0, 1))
tilt = np.asarray(sp.trajectory(sp.fit(x, texture=False, ridges=False))['tilt_db_oct'])
assert tilt[0] == pytest.approx(-3.0, abs=1.0) # pink: -3 dB / octave
assert tilt[-1] == pytest.approx(0.0, abs=1.0) # white: flat
assert tilt[-1] > tilt[0] + 2
def test_ridge_cache_renders_the_same():
rng = np.random.default_rng(7)
n = int(0.5 * SR)
t = np.arange(n) / SR
x = 0.05 * _band(rng.standard_normal(n), 200, 15000) + 0.05 * np.sin(2 * np.pi * 2500 * t)
m = sp.fit(x, texture=False)
assert m['ridges']
a = sp._mono_render(m, 31, None)
b = sp._mono_render(m, 31, None, sp._ridge_sig(m, 31))
assert np.allclose(a, b, atol=1e-9 * np.abs(a).max())
def _struck(n_s=0.4, seed=10):
"""a struck object (three decaying modes from 50 ms) in a band-noise swell; the right channel quieter"""
rng = np.random.default_rng(seed)
n = int(n_s * SR)
t = np.arange(n) / SR
tt = np.maximum(t - 0.05, 0)
modes = sum(a * np.sin(2 * np.pi * f * tt) * np.exp(-tt / d) for f, a, d in ((620, 0.3, 0.12), (1710, 0.15, 0.06),
(3380, 0.08, 0.03))) * (t >= 0.05)
x = modes + 0.03 * _band(rng.standard_normal(n), 300, 12000) * np.clip(t / 0.2, 0, 1)
return np.stack([x, 0.7 * x], 1)
def test_modal_tones_and_gain_tones():
x = _struck()
m = G.fit(x, fast=True, tones_kind='modal')
det = m['tones']
assert m['fit']['tones_kind'] == 'modal' and det['kind'] == 'modal' and m['fit']['partials'] > 0
assert det['onset'] == pytest.approx(det['strikes'][0]['t'], abs=1e-5)
assert det['onset'] == pytest.approx(0.05, abs=0.005)
y = G.render(m, seed=0)
assert y.shape == x.shape and sp.compare(x, y)['env_corr'] > 0.9
assert len(G.render(m, seed=1, length=1.3)) == pytest.approx(1.3 * len(x), abs=4)
assert 'modal' in G.summary(m)
level = lambda d: 10 * np.log10((G._tones(d, 0, True, len(x)) ** 2).sum())
assert level(det) - level(G.gain_tones(det, -20.0)) == pytest.approx(20.0, abs=0.1)
ts = G.fit(x, fast=True, tones_kind='sines')['tones'] # sines tones: partial levels and strike atoms
assert level(ts) - level(G.gain_tones(ts, -6.0)) == pytest.approx(6.0, abs=0.1)
with pytest.raises(ValueError):
G.fit(x, fast=True, tones_kind='spectral')