mirror of
https://github.com/navidrome/navidrome.git
synced 2026-10-30 23:17:51 +01:00
6486a27634* refactor(matcher): resolve matches in song-index space * test(matcher): pin per-index duration matching for duplicate title+artist songs * refactor(matcher): drop unreachable specificity sentinel * refactor(matcher): hoist PreferStarred read out of scoring loop * docs(matcher): correct config field references in MatchSongs doc * fix(matcher): log swallowed per-artist DB error in title matching * fix(matcher): fail title matching when all artist lookups error * refactor(matcher): simplify loaders and test helpers * docs(matcher): move algorithm docs to package-level doc.go * docs(matcher): focus examples on fuzzy matching behavior * refactor(matcher): store index in dedup map and harden test helper * fix(matcher): keep exact-phase matches when all title lookups fail * perf(matcher): batch title-phase artist lookups into one query matchByTitle issued one GetAll per distinct artist, run serially. On a large library a batch of similar-songs spans dozens of artists, and profiling against a 95k-track library showed the matcher was ~90% bound in that serial query loop (a 100-song batch fired ~89 separate multi-join queries, taking ~6s). Replace the loop with a single 'order_artist_name IN (...)' query, then group the returned tracks by artist in memory and score each song against its bucket. This cuts a 100-song batch from ~6s to ~0.4s (roughly 14x) with less memory. Grouping keys on order_artist_name (the field the query filters on, matching how the per-artist queries are keyed), falling back to the sanitized Artist when it is unset. Because there is now a single query, matchByTitle is all-or-nothing like the ID/MBID/ISRC loaders: the per-artist best-effort skip is gone, while resolveMatches still preserves exact-phase matches when the title query fails. * refactor(matcher): group batched title matches by order_artist_name After batching the title-phase lookups into one query, the returned tracks must be grouped back to their artist. Key on MediaFile.OrderArtistName — the exact field the query filters on — so collaboration/"feat." tracks (whose display Artist differs from the sort artist) bucket correctly, with a sanitized-Artist fallback when it is unset. OrderArtistName is deprecated in favor of Participants, but the bulk GetAll path does not hydrate participant detail (the rich artist fields come only from the per-record GetWithParticipants JOIN), so the participant order name is empty here and the column is the only populated source. Also adds a TODO in computeSpecificityLevel: its artist-MBID levels read the deprecated, unpopulated MediaFile.MbzArtistID column, so they never fire today.
108 lines
5.3 KiB
Go
108 lines
5.3 KiB
Go
// Package matcher matches song results from external agents (Last.fm, Deezer,
|
||
// etc.) to tracks in the local music library, prioritizing accuracy over recall.
|
||
//
|
||
// It exposes a single [Matcher] type with two entry points that share the same
|
||
// matching algorithm:
|
||
//
|
||
// - [Matcher.MatchSongs] returns an ordered, deduplicated slice of library
|
||
// tracks, capped at a requested count. Use it when presenting "similar
|
||
// songs" results to a client.
|
||
// - [Matcher.MatchSongsIndexed] returns a map from input-song index to matched
|
||
// track, with no deduplication. Use it when the caller needs to correlate
|
||
// each result back to its input position (e.g. to attach a per-song
|
||
// similarity score).
|
||
//
|
||
// # Algorithm Overview
|
||
//
|
||
// Each input song is resolved to its best-matching library track using four
|
||
// strategies, applied in priority order. A song matched by a higher-priority
|
||
// strategy is never reconsidered by a lower-priority one:
|
||
//
|
||
// 1. Direct ID match: songs with an ID are matched to a MediaFile by ID.
|
||
// 2. MusicBrainz Recording ID (MBID) match: songs with an MBID are matched to
|
||
// tracks with the same mbz_recording_id.
|
||
// 3. ISRC match: songs with an ISRC are matched to tracks carrying that ISRC tag.
|
||
// 4. Title+Artist fuzzy match: remaining songs are matched by fuzzy string
|
||
// comparison with metadata-specificity scoring (see below).
|
||
//
|
||
// Priority order is ID > MBID > ISRC > Title+Artist, so more reliable
|
||
// identifiers always take precedence over fuzzy text matching. Missing tracks
|
||
// (those no longer present on disk) are never matched.
|
||
//
|
||
// # Fuzzy Matching Details
|
||
//
|
||
// Title+artist matching uses Jaro-Winkler similarity, with a threshold
|
||
// configurable via conf.Server.Matcher.FuzzyThreshold (default 85%). A library
|
||
// track must clear the title threshold to be considered. Candidates that clear
|
||
// it are ranked by, in order:
|
||
//
|
||
// 1. Title similarity (Jaro-Winkler score, 0.0–1.0)
|
||
// 2. Duration proximity (closer duration scores higher; 1.0 when the agent
|
||
// reports no duration)
|
||
// 3. Preferred-track flag (enabled by conf.Server.Matcher.PreferStarred;
|
||
// prioritizes tracks that are starred or rated >= 4)
|
||
// 4. Specificity level (0–5, based on metadata precision; higher is better)
|
||
// 5. Album similarity (Jaro-Winkler, as the final tiebreaker)
|
||
//
|
||
// The specificity levels, from most to least specific, are:
|
||
//
|
||
// Level 5: Title + Artist MBID + Album MBID
|
||
// Level 4: Title + Artist MBID + Album name (fuzzy)
|
||
// Level 3: Title + Artist name + Album name (fuzzy)
|
||
// Level 2: Title + Artist MBID
|
||
// Level 1: Title + Artist name
|
||
// Level 0: Title only
|
||
//
|
||
// The title phase always requires an agent artist to scope the library query, so
|
||
// Level 0 does not mean "no artist": it applies when a candidate matches on title
|
||
// but its own artist differs from the query's (e.g. a cover or a featured-artist
|
||
// credit), leaving the title as the only shared field.
|
||
//
|
||
// Each input song is scored independently, so two songs with the same title and
|
||
// artist but different durations can resolve to different library tracks (each
|
||
// matches the track closest to its own duration).
|
||
//
|
||
// # Examples
|
||
//
|
||
// All examples below exercise the title+artist phase, where the interesting
|
||
// behavior lives. (Identifier phases — ID, MBID, ISRC — are exact lookups that
|
||
// always win over fuzzy matching; they need no illustration.)
|
||
//
|
||
// Title threshold — a near-miss title still matches; an exact-only threshold
|
||
// rejects it:
|
||
//
|
||
// Agent returns: {Name: "Bohemian Rhapsody", Artist: "Queen"}
|
||
// Library has: {ID: "t1", Title: "Bohemian Rhapsody - Remastered", Artist: "Queen"}
|
||
// With threshold 85%: match succeeds (similarity ~0.87)
|
||
// With threshold 100%: no match (not an exact title)
|
||
//
|
||
// Specificity ranking — among candidates that clear the title threshold, a
|
||
// better album match wins:
|
||
//
|
||
// Agent returns: {Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"}
|
||
// Library has:
|
||
// {ID: "t1", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "101"} // Level 1
|
||
// {ID: "t2", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"} // Level 3
|
||
// Result: t2 (Level 3 beats Level 1 on the album match)
|
||
//
|
||
// Duration tiebreak — with title and artist equal, the closest duration wins,
|
||
// so two near-identical input songs can resolve to different tracks:
|
||
//
|
||
// Agent returns:
|
||
// {Name: "Untitled", Artist: "Interpol", Duration: 245000} // 4:05
|
||
// {Name: "Untitled", Artist: "Interpol", Duration: 600000} // 10:00 (a live take)
|
||
// Library has:
|
||
// {ID: "studio", Title: "Untitled", Artist: "Interpol", Duration: 248} // 4:08
|
||
// {ID: "live", Title: "Untitled", Artist: "Interpol", Duration: 602} // 10:02
|
||
// Result: studio for the first song, live for the second
|
||
//
|
||
// Preferred track — when conf.Server.Matcher.PreferStarred is enabled, a
|
||
// starred (or rating >= 4) track is preferred even over a more specific match,
|
||
// because the preferred flag outranks specificity:
|
||
//
|
||
// Agent returns: {Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"}
|
||
// Library has:
|
||
// {ID: "exact", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"} // Level 3
|
||
// {ID: "starred", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles", Starred: true} // Level 1, starred
|
||
// Result: starred (the preferred flag outranks the better album match)
|
||
package matcher
|