musicfetch/docs/superpowers/specs/2026-06-08-smarter-lidarr-matching-design.md

# Smarter Lidarr Matching — Design

**Date:** 2026-06-08
**Status:** Approved

## Context & Goal

Live testing of the REST API exposed a real weakness: `musicfetch`'s
`lidarr_search` trusts Lidarr's universal `/api/v1/search` ordering, which is
fuzzy and unranked. A query of `Daft Punk - Discovery` ranked a novelty remix
("Daft Punk's Discovery but it's in the SM64 Soundfont" by *Pignickel*) #1, and
the real *Discovery* by Daft Punk wasn't even top-5. The interactive CLI picker
lets a human work around this; the **API's noninteractive top-pick cannot** and
grabs garbage.

The real input shape is Shazam-style `Artist - Track`. Lidarr only grabs
**albums**, never single tracks, so we must resolve a track to the album that
contains it, then pick the best-matching Lidarr album.

**Goal:** make `lidarr_search` return a **scored, best-first** list of Lidarr
hits so the noninteractive API picks the correct album, and the CLI picker shows
good matches first. Resolve `Artist - Track` → album via MusicBrainz.

## Decisions (confirmed with user)

- **Fix in the shared `musicfetch.lidarr_search`** (not an API-only layer) — both
  the CLI picker and the API noninteractive pick benefit; no duplicated logic.
  Signature unchanged: `lidarr_search(query, limit) -> list[Hit]` (drop-in).
- **Resolve track → album via MusicBrainz** (the same upstream Lidarr uses).
  Lidarr's own track indexing is too weak. One extra HTTP call, no API key.
- **Track-first semantics** (`Artist - Track`): the right side is treated as a
  track to resolve to its album. (YouTube path already handles exact tracks; this
  makes Lidarr the accurate album/discography source.)
- **No fuzzy scoring.** Live-verified that Lidarr's `album/lookup` accepts a
  direct MusicBrainz id: `term=mbid:<release-group-mbid>` (also `term=lidarr:<mbid>`)
  returns **exactly one** album. So we resolve the album's MBID via MusicBrainz and
  ask Lidarr for that exact MBID — no difflib, no ranking heuristics. The only
  selection is deterministic release-group type-filtering inside the MusicBrainz
  step (prefer studio Album over single/comp/live).
- **YouTube fallback preserved** exactly as today (see below).

## Architecture

All changes live in the `musicfetch` binary (single file). New/changed units:

```
musicfetch
├── _split_query(query) -> (left, right|None)        # split on first " - "
├── musicbrainz_best_album(artist, track) -> dict|None
│       # MB recording search -> best release-group {album_title, artist, year, rg_mbid}
├── _lidarr_album_candidates(term) / _lidarr_artist_candidates(term) -> list[Hit]
├── _universal_search(query, limit) -> list[Hit]     # /api/v1/search last resort
└── lidarr_search(query, limit) -> list[Hit]         # REWRITTEN: MBID-exact + fallbacks
```

### Data flow

1. **`Artist - Track` query:**
   a. `musicbrainz_best_album(artist, track)` → `{album_title, artist, year, rg_mbid}`.
   b. Lidarr `GET /api/v1/album/lookup?term=mbid:<rg_mbid>` → 0 or 1 exact album → `Hit`.
   c. Enrich `Hit.year` from MB when the Lidarr hit lacks one. Return it.
2. **Single-term query (no ` - `):** `_fallback_lookup` — artist-first concatenation
   of `/artist/lookup` + `/album/lookup` for the raw term (a bare term is most often
   an artist). No scoring; the interactive picker / noninteractive top-pick consume
   the order.
3. **Fallbacks (never regress):** if MusicBrainz misses or the exact MBID lookup
   returns nothing, use `_fallback_lookup(query)` (album-first there, since a dash
   query named an album/track). If `/album/lookup` and `/artist/lookup` both yield
   nothing, fall back to the existing `/api/v1/search`. `lidarr_search` returns `[]`
   only when everything fails or the key is missing.

### MusicBrainz client details

- Endpoint: `https://musicbrainz.org/ws/2/recording?query=<lucene>&fmt=json&limit=10`
  where lucene = `artist:"<artist>" AND recording:"<track>"`.
- Headers: `User-Agent: musicfetch/2.0 (https://github.com/…)` (MB requires a
  descriptive UA). Timeout ~8s. Rate-limit: at most ~1 request/sec (a process-level
  min-interval guard; this tool makes one call per fetch so it's effectively a
  courtesy delay).
- **Release-group selection** from the returned recordings' releases:
  prefer `primary-type == "Album"` with **no** `secondary-types` (excludes
  Compilation, Live, Single, Soundtrack); among those choose the earliest
  `first-release-date`. Fall back to any release-group if none qualify. Return
  `{album_title, artist, year, rg_mbid}` or `None`.

## YouTube Fallback (unchanged, documented)

This feature does not alter fallback behavior:
- **`source=auto` (default):** `build_combined_hits` includes YouTube hits. If
  Lidarr times out or returns no results, `lidarr_search` returns `[]` and the top
  YouTube hit is picked. If a Lidarr album is picked but has no indexer release,
  `actions.perform_fetch` falls through to the top YouTube hit.
- **`source=lidarr`:** lidarr-only by design — **no** YouTube fallback (the
  explicit "force Lidarr" switch). Unchanged.

## Error Handling

- All MB and Lidarr HTTP calls are wrapped; exceptions/timeouts are caught and
  degrade to the next fallback tier. `lidarr_search` never raises.
- Empty/garbled MB JSON → treated as no match.
- Existing `DEBUG` logging extended to show MB query and chosen release-group.

## Testing

Unit tests (mock `requests`, no live network):
- `musicbrainz_best_album`: from canned MB JSON, picks studio Album over a single
  and a compilation; picks earliest among Albums; falls back to any release-group
  when no studio exists; returns `None` on empty/exception.
- `_split_query`: `"A - B"` → `("A","B")`; no dash → `("A", None)`; only first
  ` - ` splits.
- `lidarr_search`: `Artist - Track` resolves via MB then does an `mbid:` exact
  lookup returning the real album (year enriched from MB); MB miss → fallback
  lookup; fallback empty → `/api/v1/search`; no key → `[]`.

Manual live check (end of implementation): with the API pointed at the user's
Lidarr (`10.2.1.16:8686`), `lidarr_search("Daft Punk - Harder Better Faster
Stronger")` resolves to **Discovery** by Daft Punk (the exact MBID
`48117b90-a16e-34ca-a514-19c702df1158`), not a single/compilation/novelty.

## Out of Scope (YAGNI)

Caching MB responses, multi-track/album disambiguation UI, fuzzy similarity
scoring (eliminated by the `mbid:` exact lookup), MB cover-art lookup.