Add Sonic Similarity plugin for audio-based track similarity

[chrisuthe]

Sonic Similarity Plugin

This PR adds a similarity search plugin that builds a fast vector index over audio analysis data and exposes a general-purpose API for finding similar tracks.

Stacks on top of the sonic analysis provider (upstream PR music-assistant#3516).

How It Works

1. On startup, reads all AudioAnalysisData rows from the database
2. Assembles a 14-dimensional vector from each track's semantic fields
3. Normalizes vectors (z-score + L2) and inserts them into a USearch HNSW index
4. Exposes sonic_analysis/similar API for nearest-neighbor search

Vector Schema (14 dimensions)

The plugin owns the vector definition — the provider just stores semantic fields, the plugin decides how to turn them into a searchable vector.

Dims	Content
0-8	9 scalar features: bpm, energy, danceability, loudness_integrated, loudness_range, brightness, harmonic_complexity, roughness, rhythmic_regularity
9-11	Circular key encoding (sin, cos) + mode (major=1, minor=0)
12-13	Time-series variance: RMS energy dynamics, spectral centroid movement

API: sonic_analysis/similar

Single endpoint that covers every use case through parameters:

Capability	How
"Play something like this"	item_id="42", limit=1
"Build a similar-tracks list"	item_ids=["42"], limit=25, resolve=True
"Radio that drifts naturally"	item_ids=[...last 5], depth=2, diversity=0.2
"Mix these vibes"	item_ids=[a,b,c], blend_mode="union", limit=50
"Similar jazz from my NAS only"	filter_genres=["jazz"], filter_providers=["prov_local"]
Per-group distance breakdown	include_group_distances=True

Features:

• Multi-seed blending: centroid (weighted average) or union (merge neighborhoods)
• Recursive depth: expands results across generations for organic radio drift
• MMR diversity: Maximal Marginal Relevance prevents results from clustering too tightly
• Per-group distances: optional breakdown by rhythm, loudness, timbre, regularity, tonal, dynamics
• Presets: balanced, vibe, party, genre_era, discover — each weights the 6 feature groups differently
• Filtering: by provider instance, genre, exclude artists/tracks
• Backfill: bulk-analyze unanalyzed library tracks from local files

Code Organization

• vectors.py — Vector schema definition, assembly from AudioAnalysisData, normalization, corpus stats, weighted distance computation. Zero MA dependencies.
• similarity.py — Pure math: centroid blending, union merge, MMR diversity, recursive expansion. Zero MA dependencies.
• __init__.py — MA integration: USearch index management, API handlers, backfill, label mapping, metadata re-ranking, debug UI

Testing

• test_vector_assembly.py — 38 tests for vector assembly, key encoding, normalization, corpus stats, weighted distance
• test_group_distances.py — 8 tests for per-group distance breakdown
• test_similarity.py — 17 tests for pure similarity functions (centroid, union, MMR, recursive expansion)
• test_plugin_api.py — 25 tests for parameter validation, weight parsing, filters, backward compat

Debug UI

Browser-based debug console at /sonic_analysis/debug with WebSocket controls for searching similar tracks, triggering backfill, rebuilding the index, and tuning all parameters (depth, blend mode, diversity, weight sliders, presets).

Dependencies

• Requires the sonic analysis provider (upstream PR Feature: sonic analysis provider music-assistant/server#3516) to populate AudioAnalysisData fields
• Uses USearch for HNSW approximate nearest-neighbor indexing
• Uses numpy for vector math