Implement sonicSimilarity extension with real audio feature analysis

Adds internal/audiofeatures: decodes each scanned song to PCM via ffmpeg and computes actual measured characteristics — tempo (via autocorrelation of the frame energy envelope, left unset rather than guessed when a clip is too short to contain a beat), an approximate loudness figure, spectral centroid/rolloff and zero-crossing rate (via a hand-written FFT), and a 12-bin chroma vector used both for a Krumhansl-Kessler key estimate and as similarity-index input. No external DSP/ML dependency. The scanner now runs this analysis after indexing each song (as part of the already-background scan, not on any request path) and stores results in the existing audio_features table via the new database.UpsertAudioFeatures/GetAudioFeatures/ListAllAudioFeatures. internal/similarity is a small in-process nearest-neighbor index: z-score normalizes each feature dimension across the analyzed library and answers Nearest (ranked real distances) and Path (a feature-space straight-line walk from one track to another, hopping to the closest not-yet-used real song at each step — never a fabricated intermediate track). getSonicSimilarTracks and findSonicPath expose these through the standard sonicMatch response, converting distance to a normalized (0,1] similarity score. A song that hasn't been analyzed yet is simply absent from results rather than faked. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014r98AtcBbevpscWLsfwVvv
2026-08-23 08:30:20 -05:00
parent 6fb46a989e
commit b6acd63c2d
13 changed files with 1486 additions and 4 deletions
@@ -0,0 +1,203 @@
+// Package similarity builds a small in-process nearest-neighbor index
+// over numeric audio-feature vectors and uses it for two things:
+// ranking tracks by actual sonic closeness, and walking a musically
+// reasonable path between two tracks through feature space. There is
+// no external vector database — the whole index is just normalized
+// vectors held in memory, rebuilt from internal/database's
+// audio_features table whenever a caller needs it.
+package similarity
+
+import (
+	"math"
+	"sort"
+)
+
+// Item is one track's raw (un-normalized) feature vector, keyed by
+// song ID.
+type Item struct {
+	ID     string
+	Vector []float64
+}
+
+// Index holds z-score-normalized vectors for a set of tracks. Each
+// dimension is normalized independently using the mean/stddev of that
+// dimension across exactly the items the index was built from, so
+// dimensions with a wide natural range (like tempo, in BPM) don't
+// dominate Euclidean distance over dimensions with a narrow one (like a
+// normalized chroma bin).
+type Index struct {
+	ids  []string
+	norm [][]float64
+}
+
+// Build normalizes and indexes items. An item whose Vector length
+// disagrees with the first item's is dropped rather than causing a
+// panic or silently misaligning dimensions — a defensive check, not
+// something expected to trigger with correctly-produced feature rows.
+func Build(items []Item) *Index {
+	idx := &Index{}
+	if len(items) == 0 {
+		return idx
+	}
+	dims := len(items[0].Vector)
+
+	var kept []Item
+	for _, it := range items {
+		if len(it.Vector) == dims {
+			kept = append(kept, it)
+		}
+	}
+	if len(kept) == 0 {
+		return idx
+	}
+
+	means := make([]float64, dims)
+	for _, it := range kept {
+		for d, v := range it.Vector {
+			means[d] += v
+		}
+	}
+	for d := range means {
+		means[d] /= float64(len(kept))
+	}
+
+	stds := make([]float64, dims)
+	for _, it := range kept {
+		for d, v := range it.Vector {
+			diff := v - means[d]
+			stds[d] += diff * diff
+		}
+	}
+	for d := range stds {
+		stds[d] = math.Sqrt(stds[d] / float64(len(kept)))
+	}
+
+	idx.ids = make([]string, len(kept))
+	idx.norm = make([][]float64, len(kept))
+	for i, it := range kept {
+		nv := make([]float64, dims)
+		for d, v := range it.Vector {
+			if stds[d] > 1e-9 {
+				nv[d] = (v - means[d]) / stds[d]
+			}
+		}
+		idx.ids[i] = it.ID
+		idx.norm[i] = nv
+	}
+	return idx
+}
+
+// Match is one similarity result: another track and its distance from
+// the query track in normalized feature space (0 = identical, larger =
+// less similar).
+type Match struct {
+	ID       string
+	Distance float64
+}
+
+// Nearest returns up to k tracks closest to id, nearest first,
+// excluding id itself. Returns nil if id isn't in the index.
+func (idx *Index) Nearest(id string, k int) []Match {
+	pos := idx.indexOf(id)
+	if pos < 0 {
+		return nil
+	}
+	matches := make([]Match, 0, len(idx.ids)-1)
+	for i, other := range idx.ids {
+		if i == pos {
+			continue
+		}
+		matches = append(matches, Match{ID: other, Distance: euclidean(idx.norm[pos], idx.norm[i])})
+	}
+	sort.Slice(matches, func(a, b int) bool { return matches[a].Distance < matches[b].Distance })
+	if k > 0 && len(matches) > k {
+		matches = matches[:k]
+	}
+	return matches
+}
+
+// Path walks from fromID to toID in `steps` hops (including both
+// endpoints), picking at each intermediate step the not-yet-used track
+// closest to the corresponding point on the straight line between
+// fromID's and toID's feature vectors. That keeps the sequence
+// perceptually gradual — each hop is a small, real step in sonic
+// character rather than a random jump — without ever inventing a track
+// that isn't actually in the library. Returns nil if either endpoint
+// isn't indexed.
+func (idx *Index) Path(fromID, toID string, steps int) []string {
+	fromPos := idx.indexOf(fromID)
+	toPos := idx.indexOf(toID)
+	if fromPos < 0 || toPos < 0 {
+		return nil
+	}
+	if steps < 2 {
+		steps = 2
+	}
+
+	path := []string{fromID}
+	used := map[string]bool{fromID: true, toID: true}
+	fromVec, toVec := idx.norm[fromPos], idx.norm[toPos]
+
+	for step := 1; step < steps-1; step++ {
+		t := float64(step) / float64(steps-1)
+		target := lerp(fromVec, toVec, t)
+
+		best := -1
+		bestDist := math.Inf(1)
+		for i, id := range idx.ids {
+			if used[id] {
+				continue
+			}
+			d := euclidean(idx.norm[i], target)
+			if d < bestDist {
+				bestDist = d
+				best = i
+			}
+		}
+		if best < 0 {
+			break // library exhausted; fall through with what we have
+		}
+		path = append(path, idx.ids[best])
+		used[idx.ids[best]] = true
+	}
+
+	path = append(path, toID)
+	return path
+}
+
+// DistanceBetween returns the normalized-feature-space Euclidean
+// distance between two indexed tracks, or +Inf if either isn't
+// indexed.
+func (idx *Index) DistanceBetween(idA, idB string) float64 {
+	a, b := idx.indexOf(idA), idx.indexOf(idB)
+	if a < 0 || b < 0 {
+		return math.Inf(1)
+	}
+	return euclidean(idx.norm[a], idx.norm[b])
+}
+
+func (idx *Index) indexOf(id string) int {
+	for i, v := range idx.ids {
+		if v == id {
+			return i
+		}
+	}
+	return -1
+}
+
+func euclidean(a, b []float64) float64 {
+	var sum float64
+	for i := range a {
+		d := a[i] - b[i]
+		sum += d * d
+	}
+	return math.Sqrt(sum)
+}
+
+func lerp(a, b []float64, t float64) []float64 {
+	out := make([]float64, len(a))
+	for i := range a {
+		out[i] = a[i] + (b[i]-a[i])*t
+	}
+	return out
+}
@@ -0,0 +1,116 @@
+package similarity
+
+import "testing"
+
+func tempoLibrary() []Item {
+	// A synthetic library where the only varying dimension is "tempo":
+	// songs at 60, 70, 80, ..., 150 BPM. Deterministic and needs no
+	// audio decoding, so it exercises the index math directly.
+	var items []Item
+	for i, bpm := range []float64{60, 70, 80, 90, 100, 110, 120, 130, 140, 150} {
+		items = append(items, Item{ID: idFor(i), Vector: []float64{bpm, 0, 0}})
+	}
+	return items
+}
+
+func idFor(i int) string {
+	return string(rune('a' + i))
+}
+
+func TestNearestOrdersByActualDistance(t *testing.T) {
+	idx := Build(tempoLibrary())
+	// "d" is 90 BPM; its closest neighbors by tempo should be "c" (80)
+	// and "e" (100), in that order (tie broken by index order is fine
+	// since both are exactly 10 BPM away — check the pair, not order).
+	matches := idx.Nearest("d", 2)
+	if len(matches) != 2 {
+		t.Fatalf("matches = %v, want 2", matches)
+	}
+	got := map[string]bool{matches[0].ID: true, matches[1].ID: true}
+	if !got["c"] || !got["e"] {
+		t.Errorf("nearest to d(90bpm) = %v, want {c(80bpm), e(100bpm)}", matches)
+	}
+}
+
+func TestNearestExcludesSelf(t *testing.T) {
+	idx := Build(tempoLibrary())
+	matches := idx.Nearest("a", 20)
+	for _, m := range matches {
+		if m.ID == "a" {
+			t.Fatal("Nearest must never include the query track itself")
+		}
+	}
+}
+
+func TestNearestUnknownID(t *testing.T) {
+	idx := Build(tempoLibrary())
+	if matches := idx.Nearest("does-not-exist", 5); matches != nil {
+		t.Errorf("expected nil for unknown id, got %v", matches)
+	}
+}
+
+func TestNearestFarthestIsOppositeEnd(t *testing.T) {
+	idx := Build(tempoLibrary())
+	matches := idx.Nearest("a", 20) // a = 60bpm, all 9 others
+	if len(matches) != 9 {
+		t.Fatalf("matches = %d, want 9", len(matches))
+	}
+	farthest := matches[len(matches)-1]
+	if farthest.ID != "j" { // j = 150bpm, the farthest from 60bpm
+		t.Errorf("farthest from a(60bpm) = %v, want j(150bpm)", farthest)
+	}
+}
+
+func TestPathIsMonotonicAlongTheOnlyVaryingDimension(t *testing.T) {
+	idx := Build(tempoLibrary())
+	path := idx.Path("a", "j", 5) // 60bpm -> 150bpm in 5 hops
+	if len(path) != 5 {
+		t.Fatalf("path = %v, want length 5", path)
+	}
+	if path[0] != "a" || path[len(path)-1] != "j" {
+		t.Fatalf("path endpoints = %q..%q, want a..j", path[0], path[len(path)-1])
+	}
+	seen := map[string]bool{}
+	for _, id := range path {
+		if seen[id] {
+			t.Fatalf("path repeats %q: %v", id, path)
+		}
+		seen[id] = true
+	}
+	// With tempo as the only varying dimension, a straight-line
+	// interpolation from 60 to 150 BPM should visit strictly increasing
+	// tempos.
+	bpmOf := map[string]float64{"a": 60, "b": 70, "c": 80, "d": 90, "e": 100, "f": 110, "g": 120, "h": 130, "i": 140, "j": 150}
+	for i := 1; i < len(path); i++ {
+		if bpmOf[path[i]] <= bpmOf[path[i-1]] {
+			t.Errorf("path not monotonically increasing in tempo: %v", path)
+			break
+		}
+	}
+}
+
+func TestPathUnknownEndpoint(t *testing.T) {
+	idx := Build(tempoLibrary())
+	if path := idx.Path("a", "nope", 5); path != nil {
+		t.Errorf("expected nil path for unknown endpoint, got %v", path)
+	}
+}
+
+func TestBuildEmpty(t *testing.T) {
+	idx := Build(nil)
+	if matches := idx.Nearest("a", 5); matches != nil {
+		t.Errorf("expected nil from an empty index, got %v", matches)
+	}
+}
+
+func TestBuildConstantDimensionDoesNotDivideByZero(t *testing.T) {
+	items := []Item{
+		{ID: "x", Vector: []float64{5, 1}},
+		{ID: "y", Vector: []float64{5, 2}},
+	}
+	idx := Build(items)
+	matches := idx.Nearest("x", 5)
+	if len(matches) != 1 || matches[0].ID != "y" {
+		t.Fatalf("matches = %v", matches)
+	}
+}