---
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.
