docs(tasks): log 015 — vibe search + semantic layer + landing

armada/tasks/015-vibe-search-the-sound-you-mean.md

+---
+log: 015
+title: "Vibe search — find the sound you mean, not the name you forgot"
+date: 2026-06-07
+task: "#82 semantic L2 + #86 endpoint + #87 vibe UI + #88 landing (under #64)"
+tags: [tooling, dataviz, audio, clap, ux, semantics]
+shareable: true
+---
+
+## Cap (what & why)
+Unwrapped was "raw-feature great" but you don't reach for a sound by spectral
+centroid — you reach for "a warm dusty rhodes" or "something ténébreux". Wire the
+CLAP semantic engine in: type a vibe, get the samples; click a sound, get its kin.
+And give the dataviz a front door.
+
+## Manœuvre (how)
+Katana first: validated `sample_semantics.py` on real audio before building any UI.
+Finding (below) reshaped the design toward honest similarity, not fake labels.
+- `sample_semantics embed` → `semantics_embeds.npz` (1490×512 CLAP audio embeds).
+- `serve.py`: lazy `/vibe?q=` (embed any phrase, rank) + `/similar?name=` (audio-embed
+  cosine). 503/400/404 clean; static serving untouched; torch loads once on first hit.
+- `build_unwrapped`: 2D PCA of the embeds → a semantic **vibe map** axis-pair + 16
+  seed-vibe chips (PLN's own words — the on-ramp).
+- `unwrapped.html`: vibe-search box + chips → matches light up magenta (sized by
+  similarity, top ringed) and the map flips to vibe space; shift-click → find similar.
+- `index.html` + `build_landing.py`: dataviz front door with an honest style cloud.
+
+## Prise (findings / artifacts)
+- `sample_semantics.py`, `semantics_embeds.npz`, `serve.py` /vibe+/similar,
+  `build_unwrapped.py` (vibe map), `unwrapped.html` (search), `index.html` +
+  `landing.json`. test_build_unwrapped 4 green.
+- Vibe search rings true: "jazzy upright bass" → no_sunshine/come_bass loops;
+  "warm dusty rhodes" → suns_keys gold-keys + west-coast electric; a kick's nearest
+  neighbours are kicks (0.96 cross-folder).
+- Style cloud (honest, track counts): dnb 18 · breaks 17 · techno 14 · nujazz 12.
+
+## Sel (the shareable learning)
+Per-one-shot CLAP **genre/mood is junk** — a 0.3s hit has no genre, so everything
+defaults to boom-bap/euphoric. But the **embedding distances are true**: relative
+similarity nails it even when absolute labels lie. So we shipped *search*, not *tags*,
+and pulled genre from where it's real (the tracks PLN tagged himself). Trust the
+instrument: don't let a model imply certainty the data doesn't have.
+
+## Hameçon (hook)
+Type "shadowy ténébreux pad" into a map of 1,485 of my sounds — and the right ones
+light up. The machine can't name the genre of a single drum hit, but it knows which
+sounds are cousins.