Skip to content

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

12.9 KB
Raw Blame
"""Tests for the semantics modules (vocab, describe, match, search, compare). Fast tests use synthetic signals and fake
embeddings; tests marked slow load CLAP / AST (run with --slow)."""
import json

import numpy as np
import pytest

from earshot import compare, describe, features, match, search, vocab
from earshot.report import to_json

SR = 48000


def _fake_vocab(T=40, seed=0):
    rng = np.random.RandomState(seed)
    v = vocab.Vocab.__new__(vocab.Vocab)
    v.names = [f'term {i}' for i in range(T)]
    v.cats = {'a': v.names[:T // 2], 'b': v.names[T // 2:]}
    v.cat_of = {t: ('a' if i < T // 2 else 'b') for i, t in enumerate(v.names)}
    v.E = vocab._norm(rng.randn(T, 512).astype(np.float32))
    v.m = vocab._norm(rng.randn(512).astype(np.float32)) * 0.3
    v.mu_E = v.bias(v.E)
    return v


def _clicks(times, dur=4.0, amp=0.5, seed=1):
    rng = np.random.RandomState(seed)
    x = rng.randn(int(dur * SR)).astype(np.float32) * 1e-4
    n = int(0.08 * SR)
    burst = rng.randn(n) * np.exp(-np.arange(n) / SR / 0.008) * amp
    for t in times:
        a = int(t * SR)
        x[a:a + n] += burst.astype(np.float32)
    return x


# ---------------------------------------------------------------------------------------------------- vocab
def test_vocab_json_schema():
    d = vocab.load_vocab()
    assert set(d) >= {'templates', 'categories'}
    assert all('{}' in t for t in d['templates'])
    terms = [t for ts in d['categories'].values() for t in ts]
    assert len(terms) == len(set(terms)) and len(terms) > 200
    assert set(vocab.UNVALIDATED) <= set(d['categories'])


def test_stats_file_matches_vocab_and_model():
    s = vocab.load_stats()
    assert s is not None and len(s['mean']) == 512 and s['pad'] == vocab.PAD
    assert set(vocab.load_vocab()['templates']) == set(s['templates'])
    assert s['n_ref'] >= 100


def test_spans_for():
    assert vocab.spans_for(0.0, 3.0) == [(0.0, 3.0)]
    sp = vocab.spans_for(0.0, 25.0, max_win=None)
    assert [round(a, 3) for a, _ in sp] == [0.0, 5.0, 10.0, 15.0] and sp[-1][1] == pytest.approx(25.0)
    sp = vocab.spans_for(2.0, 12.5, max_win=None)        # last window flush with the end
    assert sp[0] == (2.0, 12.0) and sp[-1][1] == pytest.approx(12.5)
    sp = vocab.spans_for(0.0, 170.0, max_win=6)
    assert len(sp) == 6 and sp[0][0] == 0.0 and sp[-1][1] == pytest.approx(170.0)
    assert all(b - a == pytest.approx(10.0) for a, b in sp)


def test_group_weights_balance_folders(tmp_path):
    paths = [str(tmp_path / 'a' / f'{i}.wav') for i in range(4)] + [str(tmp_path / 'b' / 'x.wav')]
    w = vocab.group_weights(paths)
    assert w[:4].sum() == pytest.approx(w[4])


def test_calibrate_math():
    v = _fake_vocab()
    rng = np.random.RandomState(3)
    A = vocab._norm(rng.randn(5, 512).astype(np.float32))
    r = v.calibrate(A, v.E[:3], 'both')
    assert np.allclose(r['z_t'].mean(1), 0, atol=1e-5) and np.allclose(r['z_t'].std(1), 1, atol=1e-4)
    assert np.allclose(r['z_q'], r['z_t'][:, :3], atol=1e-5)      # a query equal to a term scores like the term
    assert np.allclose(r['cos_q'], A @ v.E[:3].T)
    raw = v.calibrate(A, v.E[:3], 'raw')
    assert np.allclose(raw['z_q'], raw['cos_q'])
    c = v.calibrate(A, None, 'center')
    assert np.allclose(c['u_t'], A @ v.E.T - v.E @ v.m, atol=1e-5)
    assert ((r['pct_q'] >= 0) & (r['pct_q'] <= 1)).all()


def test_top_terms_filters_categories():
    v = _fake_vocab()
    a = v.E[25] * 0.9 + v.E[3] * 0.1
    a /= np.linalg.norm(a)
    top = v.top_terms(a, k=3)
    assert top[0][0] == 'term 25' and top[0][2] > 2
    assert all(c == 'a' for _, c, _, _ in v.top_terms(a, k=5, cats=('a',)))
    assert all(c != 'b' for _, c, _, _ in v.top_terms(a, k=5, exclude=('b',)))


# ---------------------------------------------------------------------------------------------------- match
def test_verdict_thresholds_ordered():
    zs = [t for t, _ in match.VERDICTS]
    assert zs == sorted(zs, reverse=True)
    assert match.verdict(zs[0] + 0.01) == 'strong' and match.verdict(-5) == 'no match'
    assert set(match.VERDICT_EVIDENCE) == {name for _, name in match.VERDICTS} | {'no match'}
    lrs = [match.VERDICT_EVIDENCE[n]['lr'] for _, n in match.VERDICTS] + [match.VERDICT_EVIDENCE['no match']['lr']]
    assert lrs == sorted(lrs, reverse=True) and lrs[-1] < 1      # bands, each stronger evidence than the next


def test_z_text_never_contradicts_verdict():
    assert vocab.zf(2.96) == '+2.9' and vocab.zf(3.0) == '+3.0' and vocab.zf(-0.04) == '-0.1'
    for z in np.arange(1.5, 3.5, 0.01):
        assert match.verdict(float(vocab.zf(z))) == match.verdict(z) or float(vocab.zf(z)) < z


def test_check_rejects_bad_ranges(wav, click):
    p = wav(click)
    assert vocab.check(p) == pytest.approx(0.25)
    with pytest.raises(ValueError):
        vocab.check(p, start=1.0)
    with pytest.raises(ValueError):
        vocab.check(p, start=0.1, end=0.05)
    with pytest.raises(Exception):
        vocab.check(p + '.missing.wav')
    with pytest.raises(ValueError):
        match.match(p, [])


def test_readable_skips_bad_files(wav, click, tmp_path):
    bad = tmp_path / 'not_audio.wav'
    bad.write_bytes(b'this is not audio')
    ok, skipped = vocab.readable([wav(click), str(bad)])
    assert len(ok) == 1 and skipped[0]['path'] == str(bad) and skipped[0]['error']


def test_softmax_is_a_distribution():
    p = match.softmax([0.3, 0.25, 0.1], 38.7)
    assert p.sum() == pytest.approx(1.0) and p[0] > p[1] > p[2]


# ---------------------------------------------------------------------------------------------------- search
def test_event_candidates_land_on_clicks():
    times = [0.5, 1.5, 2.6]
    x = _clicks(times)
    c = search.event_candidates(x)
    strokes = sorted(s for s in c if s[2] == 'stroke')
    assert len(strokes) == 3
    for (s, e, _, _), t in zip(strokes, times):
        assert t - 0.015 <= s <= t + 0.002          # trim starts just before the attack, never after it
        assert 0.02 < e - s < 0.5                    # ends after the decay, long before the next click


def test_down_up_strokes_are_paired():
    x = _clicks([0.5, 0.62, 1.8, 1.92], amp=0.5)
    c = search.event_candidates(x)
    pairs = sorted((round(s, 2), round(e, 2)) for s, e, k, _ in c if k == 'event')
    assert len(pairs) == 2 and pairs[0][0] == pytest.approx(0.49, abs=0.02) and pairs[0][1] > 0.62


def test_select_round_robin_covers_time():
    cands = [(t, t + 0.1, 'stroke', 50.0) for t in np.arange(0, 4, 0.05)] + [(10.0, 10.1, 'stroke', 1.0)]
    sel = search._select(cands, n=6, bucket=2.0)
    assert len(sel) == 6 and any(s[0] >= 10 for s in sel)


def test_window_candidates_cover_everything():
    w = search.window_candidates(18.0)
    assert w[0][:2] == (0.0, 3.0) and w[-1][1] == pytest.approx(18.0)
    assert search.window_candidates(0.5) == [(0.0, 0.5, 'window', 0.0)]
    for dur in (44.0, 300.0, 600.0, 1800.0):              # no gaps anywhere, whatever the length
        w = search.window_candidates(dur)
        assert w[0][0] == 0.0 and w[-1][1] == pytest.approx(dur)
        assert all(b[0] <= a[1] + 1e-6 for a, b in zip(w, w[1:]))
        assert all(b - a <= search.MAX_WIN_S + 1e-6 for a, b, _, _ in w)
    assert len(search.window_candidates(300.0)) <= search.MAX_WINDOWS
    w = search.window_candidates(12.0, t0=5.1)               # a --start/--end range in local time
    assert w[0][0] == 5.1 and w[-1][1] == pytest.approx(12.0)


def test_event_candidates_span_a_long_file():
    x = _clicks(list(np.arange(0.5, 299, 1.0)), dur=300.0, amp=0.3)
    allc = search.event_candidates(x, n=None)
    assert max(c[0] for c in allc) > 290                    # every onset is a candidate before any selection
    assert len(search.event_candidates(x)) <= search.MAX_EVENTS


def test_dedupe():
    c = [(0.0, 1.0, 'stroke', 1), (0.01, 1.0, 'event', 1), (2.0, 3.0, 'stroke', 1)]
    assert len(search._dedupe(c)) == 2


def test_tail_db():
    x = _clicks([0.5])
    env = search._env_db(x)
    assert search._tail_db(env, 0.495, 0.7) < -30
    assert search._tail_db(env, 0.495, 0.505) > -15


# ---------------------------------------------------------------------------------------------------- compare / describe
def _f(x):
    return compare.feats(features.measure(x, light=True), x)


def test_differences_in_words(click, sine):
    fa, fb = _f(sine * 0.1), _f(click)
    keys, txt = compare.differences(fa, fb)
    assert 'brightness_hz' in keys and 'brighter (brightness' in txt and len(keys) <= 4
    keys, txt = compare.differences(fa, dict(fa, loudness_lufs=fa['loudness_lufs'] + 6))
    assert keys == ['loudness_lufs'] and txt.startswith('6 dB louder')
    assert compare.differences(fa, fa)[0] == []


def test_trims_of_the_same_sound_read_the_same(click):
    short = click[: int(0.05 * SR)]
    for pad_s in (0.3, 0.5, 2.0):                           # extra silence after (and before) the same click
        padded = np.concatenate([np.zeros(int(0.1 * SR), np.float32), short, np.zeros(int(pad_s * SR), np.float32)])
        keys, txt = compare.differences(_f(short), _f(padded))
        assert keys == [], (pad_s, txt)
    st = np.stack([short, short], axis=1)                    # dual mono = mono: no width difference
    assert compare.differences(_f(short), _f(st))[0] == []
    assert _f(short)['width_db'] == compare.MONO_DB and 'noise_floor_dbfs' not in _f(short)


def test_closer_is_none_when_too_close():
    assert compare._closer(2.9, 2.91) == (None, 'Neither is closer')
    assert compare._closer(1.0, 2.5)[0] == 'b' and compare._closer(2.0, 1.6)[0] == 'a'


def test_typicality_flags_outlier():
    rng = np.random.RandomState(0)
    c = vocab._norm(rng.randn(512))
    R = vocab._norm(c + 0.3 * vocab._norm(rng.randn(12, 512)))
    inlier = vocab._norm(c + 0.3 * vocab._norm(rng.randn(512)))
    outlier = vocab._norm(rng.randn(512))
    assert compare._typicality(inlier, R, 3)[1] > -1
    assert compare._typicality(outlier, R, 3)[1] < -2


def test_shape_words(click, sine):
    assert 'short transient' in describe.shape(features.measure(click))
    s = describe.shape(features.measure(sine))
    assert 'tonal' in s and 'A5' in s


def test_distinct_windows_do_not_overlap_or_repeat():
    rng = np.random.RandomState(0)
    W = vocab._norm(np.repeat(rng.randn(1, 512), 6, axis=0) + 0.01 * rng.randn(6, 512))
    W[4] = vocab._norm(rng.randn(512))
    spans = [(5.0 * i, 5.0 * i + 10) for i in range(6)]
    tags = ['x', 'x', 'y', 'x', 'z', 'x']
    idx = describe.distinct_windows(spans, W, tags, n=3)
    assert 4 in idx and len(idx) >= 2
    assert all(spans[a][1] <= spans[b][0] for a, b in zip(idx, idx[1:]))
    assert len({tags[i] for i in idx}) == len(idx)
    assert describe.distinct_windows(spans, W, ['x'] * 6) == []      # uniform: nothing reads differently


def test_measurements_hide_what_is_not_measurable(click):
    m = describe.measurements(features.measure(click))
    assert m['width'] == 'mono' and 'noise_floor_dbfs' not in m and 'centroid_hz' not in m


# ---------------------------------------------------------------------------------------------------- with models
@pytest.mark.slow
def test_match_and_describe_end_to_end(wav, click):
    p = wav(np.concatenate([click, np.zeros(SR // 4, np.float32)]))
    r = match.match(p, ['a short click', 'a choir singing'], alts=['music'])
    json.loads(to_json(r))
    assert {'query', 'cosine', 'z', 'percentile', 'rank_in_vocab', 'p_vs_alts', 'verdict', 'summary'} <= set(r)
    assert r['results'][0]['z'] >= r['results'][1]['z']
    d = describe.describe(p)
    json.loads(to_json(d))
    assert d['top_tags'] and d['audioset'] and 'Sounds most like' in d['summary']
    assert all(t['category'] not in vocab.UNVALIDATED for t in d['top_tags'])
    tiny = describe.describe(wav(click[:100], 'tiny.wav'))
    assert 'too short' in tiny['summary'] and tiny['top_tags'] == []
    silent = describe.describe(wav(np.zeros(SR, np.float32), 'silence.wav'))
    assert 'near-silence' in silent['summary']


@pytest.mark.slow
def test_rank_skips_unreadable_and_flags_silence(wav, click, tmp_path):
    wav(click, 'click.wav')
    wav(np.zeros(SR, np.float32), 'silence.wav')
    (tmp_path / 'broken.wav').write_bytes(b'not audio at all')
    r = search.rank([str(tmp_path)], 'a short click')
    json.loads(to_json(r))
    assert r['n_files'] == 2 and len(r['skipped']) == 1
    assert r['results'][-1]['name'] == 'silence.wav' and r['results'][-1]['near_silent']
    assert 'unreadable' in r['summary'] and 'near-silent' in r['summary']


@pytest.mark.slow
def test_find_segments_hold_the_clicks(wav):
    times = [1.0, 3.0, 5.0]
    r = search.find(wav(_clicks(times, dur=6.0)), 'a single click', top=3)
    json.loads(to_json(r))
    assert r['query_kind'] == 'event' and len(r['segments']) == 3
    held = sorted(next(t for t in times if s['start'] <= t < s['end']) for s in r['segments'])
    assert held == times                                  # three non-overlapping segments, one per click
    r = search.find(wav(_clicks(times, dur=6.0), 'r.wav'), 'a single click', top=3, start=2.9, end=6.0)
    assert r['segments'] and all(s['start'] >= 2.9 - search.PRE_ROLL - 1e-3 for s in r['segments'])