Clean release snapshot

docs/benchmarks/note_detect_bass_v1/BENCHMARK.md

@@ -0,0 +1,34 @@
+# Slopsmith Note Detect Bass Benchmark — v1
+
+A bass-focused companion to the guitar benchmarks
+(note_detect_v1 + note_detect_v2). Tests `note_detect` against bass-
+specific idioms: walking lines, octave jumps, root+fifth patterns,
+double-stops, and long low-E holds that stress YIN's accumulator at
+~41 Hz.
+
+- **Tempo**: 90 BPM
+- **Tuning**: E standard 4-string (E1 A1 D2 G2, no capo)
+- **Audio**: metronome click track only — play *over* the click.
+- **Duration**: 181 s
+
+## Sections
+
+| Section | Tests |
+|---|---|
+| A. Open strings (slow walk) | Mono detection on each open string, low → high → low |
+| B. 5th-fret (slow walk) | Fretted-note detection across the 4 strings |
+| C. Sustained notes | 3 × 4-second held roots |
+| D. Octave walks | Root ↔ octave alternation, 2 strings + 2 frets up |
+| E. Walking bassline | A minor pentatonic ascending + descending |
+| F. Root + fifth pattern | Classic rock bass pattern (8 events) |
+| G. Double-stops | 2-string voicings — the chord-scorer test for bass |
+| H. Long low-E holds | 3 × 5-second E1 holds, stresses YIN under-buffer regime |
+
+## Reporting
+
+Diagnostic JSON schema is `note_detect.diagnostic.v1`. Filter
+`benchmark_hint` to bucket bass vs guitar runs.
+
+## Source
+
+Built by `docs/benchmarks/note_detect_bass_v1/build_benchmark.py`.

docs/benchmarks/note_detect_bass_v1/build_benchmark.py

@@ -0,0 +1,503 @@
+"""Builds the Note Detect Bass Benchmark sloppak (v1).
+
+A bass-focused companion to the guitar benchmarks (note_detect_v1 +
+note_detect_v2). Same 90 BPM click, similar half-note pacing as v2,
+but the sections are built around what bass actually plays: single-
+note lines, octave jumps, walking patterns, sustained roots, and
+two-string double-stops (the closest bass gets to "chords").
+
+Why a separate bass benchmark instead of toggling string count on
+the guitar one:
+
+- Tuning is different — 4-string bass open MIDI is [28, 33, 38, 43]
+  (E1, A1, D2, G2) vs the guitar's [40, 45, 50, 55, 59, 64]. The
+  benchmark needs to produce notes the player can actually play on
+  the instrument they have plugged in.
+- Bass idioms are different from guitar idioms. Strumming sections
+  don't apply; walking bass + octave patterns do.
+- Low-frequency detection is materially harder for YIN — E1 at
+  ~41 Hz needs more accumulated samples for confident detection
+  than guitar E2 at ~82 Hz. The benchmark should exercise that
+  regime explicitly so we can spot regressions there.
+
+How to run inside the slopsmith container:
+
+    docker cp docs/benchmarks/note_detect_bass_v1/build_benchmark.py \\
+              slopsmith-web-1:/tmp/build_benchmark_bass.py
+    docker exec slopsmith-web-1 python /tmp/build_benchmark_bass.py \\
+              /app/static/sloppak_cache/note_detect_benchmark_bass_v1.sloppak
+
+After regenerating, copy the zip output to the tracked path with the
+`.sloppak` (not `.sloppak.zip`) suffix.
+"""
+
+import json
+import math
+import shutil
+import struct
+import subprocess
+import sys
+import wave
+from pathlib import Path
+
+import yaml
+
+# ── Benchmark parameters ────────────────────────────────────────────────
+BPM = 90.0
+SECONDS_PER_BEAT = 60.0 / BPM
+BEATS_PER_BAR = 4
+BAR_S = BEATS_PER_BAR * SECONDS_PER_BEAT
+INTRO_BARS = 2
+OUTRO_BARS = 2
+EXERCISE_BARS = 8
+
+# 4-string bass open MIDI per string, low → high.
+# Matches lib/tunings convention used by note_detect when the
+# arrangement is 'bass' and stringCount is 4.
+OPEN_MIDI = [28, 33, 38, 43]  # E1 A1 D2 G2
+N_STRINGS = 4
+
+SR = 44100
+
+
+# ── Click-track audio generator ────────────────────────────────────────
+def _sine_burst(freq_hz, duration_s, amplitude):
+    n = int(SR * duration_s)
+    out = []
+    fade = max(1, int(0.004 * SR))
+    for i in range(n):
+        env = 1.0
+        if i < fade:
+            env = i / fade
+        elif i >= n - fade:
+            env = (n - 1 - i) / fade
+        s = math.sin(2 * math.pi * freq_hz * (i / SR)) * amplitude * env
+        out.append(max(-1.0, min(1.0, s)))
+    return out
+
+
+def write_click_wav(path: Path, duration_s: float):
+    total_samples = int(SR * duration_s)
+    pcm = [0] * total_samples
+    beat = 0
+    t = 0.0
+    while t < duration_s:
+        is_downbeat = (beat % BEATS_PER_BAR == 0)
+        freq = 1200 if is_downbeat else 800
+        amp = 0.6 if is_downbeat else 0.35
+        burst = _sine_burst(freq, 0.040, amp)
+        start = int(t * SR)
+        for i, s in enumerate(burst):
+            j = start + i
+            if 0 <= j < total_samples:
+                pcm[j] = int(max(-1.0, min(1.0, pcm[j] / 32767 + s)) * 32767)
+        t += SECONDS_PER_BEAT
+        beat += 1
+
+    pcm = [struct.pack('<h', v) for v in pcm]
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with wave.open(str(path), 'wb') as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(SR)
+        w.writeframes(bytes(b''.join(pcm)))
+
+
+# ── Chart helpers ─────────────────────────────────────────────────────
+def note(t, s, f, sus=0.0, **flags):
+    return {
+        't': round(t, 3),
+        's': s,
+        'f': f,
+        'sus': round(sus, 3),
+        'sl': flags.get('sl', -1),
+        'slu': flags.get('slu', -1),
+        'bn': flags.get('bn', 0.0),
+        'ho': flags.get('ho', False),
+        'po': flags.get('po', False),
+        'hm': flags.get('hm', False),
+        'hp': flags.get('hp', False),
+        'pm': flags.get('pm', False),
+        'mt': flags.get('mt', False),
+        'vb': flags.get('vb', False),
+        'tr': flags.get('tr', False),
+        'ac': flags.get('ac', False),
+        'tp': flags.get('tp', False),
+    }
+
+
+def chord(t, id_, notes):
+    return {
+        't': round(t, 3),
+        'id': id_,
+        'hd': False,
+        'notes': notes,
+    }
+
+
+def chord_note(s, f, sus=0.0, **flags):
+    n = note(0.0, s, f, sus, **flags)
+    n.pop('t')
+    return n
+
+
+# ── Exercises ─────────────────────────────────────────────────────────
+# Bass idioms: single notes dominate, occasional double-stops (root +
+# fifth on adjacent higher string two frets up, or root + octave two
+# strings + two frets up), long sustains. Half-note pacing throughout
+# for the same "give the player time to land cleanly" reasoning as
+# guitar v2.
+
+def exercise_open_strings_slow(t0):
+    """All 4 open strings, low → high → low. Tests the lowest end of
+    YIN's range (E1 = 41 Hz) where the under-buffering threshold
+    kicks in."""
+    seq = [0, 1, 2, 3, 3, 2, 1, 0]
+    notes_out = []
+    for i, s in enumerate(seq):
+        notes_out.append(note(t0 + i * 2 * SECONDS_PER_BEAT, s, 0,
+                              sus=SECONDS_PER_BEAT * 1.6))
+    notes_out[-1]['sus'] = round(SECONDS_PER_BEAT * 4, 3)
+    return notes_out, [], 'Open strings (slow walk)'
+
+
+def exercise_fretted_5th_slow(t0):
+    """5th fret on each string, ascending. Maps to A1 / D2 / G2 / C3
+    — comfortable register for hand position, no stretch."""
+    seq = [(s, 5) for s in range(N_STRINGS)]
+    notes_out = []
+    for i, (s, f) in enumerate(seq):
+        notes_out.append(note(t0 + i * 2 * SECONDS_PER_BEAT, s, f,
+                              sus=SECONDS_PER_BEAT * 1.6))
+    notes_out[-1]['sus'] = round(SECONDS_PER_BEAT * 4, 3)
+    return notes_out, [], 'Fretted positions (5th fret, slow walk)'
+
+
+def exercise_sustained(t0):
+    """Three 4-second sustained roots across the range. Tests the
+    `_sustainStillHeld` active-glow path on bass tonalities."""
+    sus = 4.0
+    targets = [(0, 5), (1, 7), (2, 5)]   # A1, E2, G2 — spread across mid-range
+    notes_out = []
+    for i, (s, f) in enumerate(targets):
+        notes_out.append(note(t0 + i * (sus + 1.0), s, f, sus=sus))
+    return notes_out, [], 'Sustained notes (3 holds, 4 s each)'
+
+
+def exercise_octave_walk(t0):
+    """Octave jumps — common bass pattern (root note + octave on the
+    string two above). Pairs: (0,0)↔(2,2) = E1↔E2 octave. Plays root,
+    octave, root, octave at half-note pacing."""
+    pairs = [
+        (0, 0, 2, 2),    # E1 ↔ E2
+        (1, 0, 3, 2),    # A1 ↔ A2
+    ]
+    notes_out = []
+    t = 0.0
+    for (sa, fa, sb, fb) in pairs:
+        notes_out.append(note(t0 + t, sa, fa, sus=SECONDS_PER_BEAT * 1.6))
+        t += 2 * SECONDS_PER_BEAT
+        notes_out.append(note(t0 + t, sb, fb, sus=SECONDS_PER_BEAT * 1.6))
+        t += 2 * SECONDS_PER_BEAT
+        notes_out.append(note(t0 + t, sa, fa, sus=SECONDS_PER_BEAT * 1.6))
+        t += 2 * SECONDS_PER_BEAT
+        notes_out.append(note(t0 + t, sb, fb, sus=SECONDS_PER_BEAT * 1.6))
+        t += 2 * SECONDS_PER_BEAT
+    notes_out[-1]['sus'] = round(SECONDS_PER_BEAT * 2, 3)
+    return notes_out, [], 'Octave walks (root ↔ octave)'
+
+
+def exercise_walking_line(t0):
+    """Walking bassline — root, third, fifth, sixth ascending, then
+    descending. Classic 4-bar walking pattern in A minor pentatonic
+    starting on A string open. Tests detection across a fretted run."""
+    # A1, C2, D2, E2 (ascend), E2, D2, C2, A1 (descend)
+    pattern = [
+        (1, 0),  # A1
+        (1, 3),  # C2
+        (1, 5),  # D2
+        (1, 7),  # E2
+        (1, 7),  # E2
+        (1, 5),  # D2
+        (1, 3),  # C2
+        (1, 0),  # A1
+    ]
+    notes_out = []
+    for i, (s, f) in enumerate(pattern):
+        notes_out.append(note(t0 + i * 2 * SECONDS_PER_BEAT, s, f,
+                              sus=SECONDS_PER_BEAT * 1.6))
+    notes_out[-1]['sus'] = round(SECONDS_PER_BEAT * 4, 3)
+    return notes_out, [], 'Walking bassline (A minor pentatonic)'
+
+
+def exercise_root_fifth_pattern(t0):
+    """Root + fifth alternation — single most common bass pattern in
+    rock / country. Plays (root, fifth, root, fifth) on each of two
+    voicings. The fifth sits on the next-higher string, 2 frets up
+    from the root — a one-finger reach with no string skip."""
+    # Root on (0, 0) = E1, fifth = (1, 2) = B1 (A string fret 2)
+    # Then root on (1, 0) = A1, fifth = (2, 2) = E2 (D string fret 2)
+    pattern = [
+        (0, 0), (1, 2), (0, 0), (1, 2),
+        (1, 0), (2, 2), (1, 0), (2, 2),
+    ]
+    notes_out = []
+    for i, (s, f) in enumerate(pattern):
+        notes_out.append(note(t0 + i * 2 * SECONDS_PER_BEAT, s, f,
+                              sus=SECONDS_PER_BEAT * 1.6))
+    notes_out[-1]['sus'] = round(SECONDS_PER_BEAT * 4, 3)
+    return notes_out, [], 'Root + fifth pattern'
+
+
+def exercise_double_stops(t0):
+    """Two-string "chord" events — closest bass gets to chords.
+    Root + fifth simultaneously on adjacent strings, repeated 8
+    times at half-note pacing. Lets the chord scorer exercise the
+    2-string code path with bass-range frequencies."""
+    # Voicing: E1 + B1 (root + fifth on E + A strings)
+    voicing = [(0, 0), (1, 2)]
+    strums = 8
+    chords_out = []
+    sus = SECONDS_PER_BEAT * 1.6
+    # Sloppak wire spec keeps chord-template fingers/frets in six-slot
+    # arrays even for bass (docs/sloppak-spec.md §chord-template), so we
+    # pad the unused two slots with -1; the chord notes themselves stay
+    # on strings 0–1.
+    template = {
+        'name': 'E5 (bass)', 'displayName': 'E5', 'arp': False,
+        'fingers': [-1, -1, -1, -1, -1, -1],
+        'frets':   [ 0,  2, -1, -1, -1, -1],
+    }
+    for i in range(strums):
+        chord_notes = [chord_note(s, f, sus=sus) for (s, f) in voicing]
+        chords_out.append(chord(t0 + i * 2 * SECONDS_PER_BEAT, 0, chord_notes))
+    return [], (chords_out, [template]), 'Double-stops (root + fifth, 8 strums)'
+
+
+def exercise_low_e_long_holds(t0):
+    """Three long-held low E (open string, lowest note on the
+    instrument). Specifically targets YIN's under-buffering regime
+    — E1 at 41 Hz needs roughly 4096 samples for a confident lock
+    at 44.1 kHz, so the detector should spend ~95 ms accumulating
+    before it can report. Holds of 5 s each give the scorer huge
+    runway; if the detector can't lock here it can't lock anywhere."""
+    sus = 5.0
+    notes_out = []
+    for i in range(3):
+        notes_out.append(note(t0 + i * (sus + 0.5), 0, 0, sus=sus))
+    return notes_out, [], 'Long low-E holds (5 s each)'
+
+
+EXERCISES = [
+    ('A. Open strings (slow)',     exercise_open_strings_slow),
+    ('B. 5th-fret (slow)',         exercise_fretted_5th_slow),
+    ('C. Sustained notes',         exercise_sustained),
+    ('D. Octave walks',            exercise_octave_walk),
+    ('E. Walking bassline',        exercise_walking_line),
+    ('F. Root + fifth pattern',    exercise_root_fifth_pattern),
+    ('G. Double-stops (root + 5)', exercise_double_stops),
+    ('H. Long low-E holds',        exercise_low_e_long_holds),
+]
+
+
+# ── Driver ─────────────────────────────────────────────────────────────
+def build(out_dir: Path):
+    notes_all = []
+    chords_all = []
+    templates_all = []
+    sections = []
+    beats = []
+
+    t = INTRO_BARS * BAR_S
+    for label, fn in EXERCISES:
+        sections.append({'name': label, 'number': len(sections) + 1, 'time': round(t, 3)})
+        result = fn(t)
+        ns, ch_or_tuple, _desc = result
+        notes_all.extend(ns)
+        if isinstance(ch_or_tuple, tuple):
+            cs, tmpls = ch_or_tuple
+            # Rebase section-local chord template ids — see v1/v2
+            # builders for the full explanation. Bass v1 only has one
+            # chord exercise today (double-stops), but applying the
+            # same offset pattern future-proofs the driver against the
+            # day someone adds a second chord exercise that also uses
+            # local-zero-based ids.
+            offset = len(templates_all)
+            for c in cs:
+                c['id'] = c.get('id', 0) + offset
+            chords_all.extend(cs)
+            templates_all.extend(tmpls)
+        else:
+            chords_all.extend(ch_or_tuple)
+        t += EXERCISE_BARS * BAR_S
+
+    end_t = t + OUTRO_BARS * BAR_S
+
+    bar_count = 0
+    bt = 0.0
+    while bt < end_t:
+        is_downbeat = abs(bt % BAR_S) < 1e-3
+        if is_downbeat:
+            bar_count += 1
+            beats.append({'time': round(bt, 3), 'measure': bar_count})
+        else:
+            beats.append({'time': round(bt, 3), 'measure': -1})
+        bt += SECONDS_PER_BEAT
+
+    anchors = [{'time': 0.0, 'fret': 1, 'width': 12}]
+    for sec in sections:
+        anchors.append({'time': sec['time'], 'fret': 1, 'width': 12})
+
+    arrangement = {
+        'name': 'Bass',
+        # Pad to 6 slots even on bass — slopsmith's `tuning_name()` only
+        # recognises named tunings (E Standard, Drop D, etc.) on 6-element
+        # arrays, so a 4-element array shows up in the library card as the
+        # raw numeric form ("0 0 0 0") instead of "E Standard". The
+        # arrangement name ("Bass") + note positions still drive the
+        # detector's bass-specific behaviour; this just makes the library
+        # display friendly.
+        'tuning': [0] * 6,
+        'capo': 0,
+        'notes': sorted(notes_all, key=lambda n: n['t']),
+        'chords': sorted(chords_all, key=lambda c: c['t']),
+        'anchors': anchors,
+        'handshapes': [],
+        'templates': templates_all,
+        'beats': beats,
+        'sections': sections,
+    }
+
+    manifest = {
+        'title': 'Note Detect Bass Benchmark v1',
+        'artist': 'Slopsmith',
+        'album': 'Note Detection Benchmark',
+        'year': 2026,
+        'duration': round(end_t, 3),
+        'arrangements': [
+            {
+                'id': 'bass',
+                'name': 'Bass',
+                'file': 'arrangements/bass.json',
+                # Pad to 6 slots — see arrangement-level comment.
+                'tuning': [0] * 6,
+                'capo': 0,
+            },
+        ],
+        'stems': [
+            {'id': 'full', 'file': 'stems/full.ogg', 'default': True},
+        ],
+        'benchmark': {
+            'id': 'slopsmith-note-detect-benchmark-bass',
+            'version': 1,
+        },
+    }
+
+    out_dir = Path(out_dir)
+    if out_dir.exists():
+        # Defensive — see v1 builder. Only rmtree something that looks
+        # like a sloppak so a typo on the CLI doesn't nuke an unrelated
+        # directory.
+        if not (out_dir.suffix == '.sloppak'
+                or (out_dir / 'manifest.yaml').exists()):
+            raise RuntimeError(
+                f"refusing to rmtree {out_dir!r}: does not look like a sloppak "
+                f"(no .sloppak suffix, no manifest.yaml)."
+            )
+        shutil.rmtree(out_dir)
+    out_dir.mkdir(parents=True)
+    (out_dir / 'arrangements').mkdir()
+    (out_dir / 'stems').mkdir()
+
+    (out_dir / 'manifest.yaml').write_text(
+        yaml.safe_dump(manifest, sort_keys=False, allow_unicode=True),
+        encoding='utf-8',
+    )
+    (out_dir / 'arrangements' / 'bass.json').write_text(
+        json.dumps(arrangement, separators=(',', ':')),
+        encoding='utf-8',
+    )
+
+    wav_path = out_dir / 'stems' / 'full.wav'
+    write_click_wav(wav_path, end_t)
+    ogg_path = out_dir / 'stems' / 'full.ogg'
+    subprocess.run(
+        ['ffmpeg', '-y', '-loglevel', 'error',
+         '-i', str(wav_path),
+         '-c:a', 'libvorbis', '-q:a', '5',
+         str(ogg_path)],
+        check=True,
+    )
+    wav_path.unlink()
+
+    (out_dir / 'BENCHMARK.md').write_text(_benchmark_readme(end_t), encoding='utf-8')
+    _build_zip(out_dir)
+
+    print(f'Built {out_dir}')
+    print(f'        {out_dir}.zip')
+    print(f'  Duration: {end_t:.1f} s')
+    print(f'  Notes:    {len(arrangement["notes"])}')
+    print(f'  Chords:   {len(arrangement["chords"])}')
+    print(f'  Templates:{len(arrangement["templates"])}')
+
+
+def _build_zip(src_dir: Path):
+    """Pack with fixed dates / attrs for zip-metadata reproducibility.
+    See v1 guitar builder docstring for full caveats."""
+    import zipfile
+    zip_path = src_dir.with_suffix(src_dir.suffix + '.zip')
+    if zip_path.exists():
+        zip_path.unlink()
+    with zipfile.ZipFile(zip_path, 'w', compression=zipfile.ZIP_DEFLATED) as zf:
+        for p in sorted(src_dir.rglob('*')):
+            if p.is_file():
+                rel = p.relative_to(src_dir).as_posix()
+                info = zipfile.ZipInfo(filename=rel, date_time=(1980, 1, 1, 0, 0, 0))
+                info.compress_type = zipfile.ZIP_DEFLATED
+                info.external_attr = (0o644 & 0xFFFF) << 16
+                info.create_system = 3   # POSIX — see v1 builder for why
+                zf.writestr(info, p.read_bytes())
+
+
+def _benchmark_readme(duration_s):
+    return f"""# Slopsmith Note Detect Bass Benchmark — v1
+
+A bass-focused companion to the guitar benchmarks
+(note_detect_v1 + note_detect_v2). Tests `note_detect` against bass-
+specific idioms: walking lines, octave jumps, root+fifth patterns,
+double-stops, and long low-E holds that stress YIN's accumulator at
+~41 Hz.
+
+- **Tempo**: {BPM:g} BPM
+- **Tuning**: E standard 4-string (E1 A1 D2 G2, no capo)
+- **Audio**: metronome click track only — play *over* the click.
+- **Duration**: {duration_s:.0f} s
+
+## Sections
+
+| Section | Tests |
+|---|---|
+| A. Open strings (slow walk) | Mono detection on each open string, low → high → low |
+| B. 5th-fret (slow walk) | Fretted-note detection across the 4 strings |
+| C. Sustained notes | 3 × 4-second held roots |
+| D. Octave walks | Root ↔ octave alternation, 2 strings + 2 frets up |
+| E. Walking bassline | A minor pentatonic ascending + descending |
+| F. Root + fifth pattern | Classic rock bass pattern (8 events) |
+| G. Double-stops | 2-string voicings — the chord-scorer test for bass |
+| H. Long low-E holds | 3 × 5-second E1 holds, stresses YIN under-buffer regime |
+
+## Reporting
+
+Diagnostic JSON schema is `note_detect.diagnostic.v1`. Filter
+`benchmark_hint` to bucket bass vs guitar runs.
+
+## Source
+
+Built by `docs/benchmarks/note_detect_bass_v1/build_benchmark.py`.
+"""
+
+
+if __name__ == '__main__':
+    out = Path(sys.argv[1]) if len(sys.argv) > 1 else Path('./note_detect_benchmark_bass_v1.sloppak')
+    build(out)