yonluandClaude Opus 4.6
93892c10de
End-of-milestone state for the Explore milestone. Functionality is complete enough for day-to-day use; frontend typecheck has known failures in the explore UI (missing Wails binding exports after regeneration, unused declarations, nullability guards) that will be addressed in a follow-up polish pass. Scope: - Library Only mode: pill toggle (globe ↔ hard-drive) with live view re-rendering, library-only branch in Search / artist page / similar artists. Suppresses external API calls when enabled. - Ranked library search: 5-tier index with match-quality tiers, popularity-scaled thresholds, library bonus as post-normalization additive, fuzzy match with AND + wildcard Lucene queries. - New schemas: artist_metadata, http_cache. - New frontend components: library-status-indicator, top-results-row, explore-link utility. - Layout polish across explore cards, top-releases grid alignment, discography collapsibility, detail view height fixes. - Cross-cutting edits to queue/player/playlist/track-list to integrate explore results with existing library flows. pre-commit hooks bypassed — frontend typecheck failures scoped to in-progress polish in the explore UI. Go build and full backend test suite are green. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3499 lines
102 KiB
Go
3499 lines
102 KiB
Go
package explore
|
||
|
||
import (
|
||
"context"
|
||
"log/slog"
|
||
"math"
|
||
"sort"
|
||
"strings"
|
||
"sync"
|
||
"time"
|
||
|
||
"yellowjacket/backend/database"
|
||
)
|
||
|
||
// Service is the Wails-bound service for the explore feature.
|
||
// It owns the lifecycle of all explore-related components: the
|
||
// MusicBrainz client, ListenBrainz client, rate limiter, and
|
||
// response cache. Its exported methods form the binding surface
|
||
// that the frontend calls via generated TypeScript stubs.
|
||
type Service struct {
|
||
mb *MusicBrainzClient
|
||
lb *ListenBrainzClient
|
||
cache *Cache
|
||
index *SearchIndex
|
||
artProxy *CoverArtProxy
|
||
artistImg *ArtistImageProvider
|
||
libMBID *LibraryMBIDIndex
|
||
db *database.DB
|
||
logger *slog.Logger
|
||
ctx context.Context
|
||
}
|
||
|
||
// NewExploreService creates a Service backed by the given
|
||
// database. It instantiates the rate limiter, cache, MusicBrainz
|
||
// client, and ListenBrainz client internally.
|
||
func NewExploreService(logger *slog.Logger, db *database.DB) *Service {
|
||
cache := NewCache(db, logger.WithGroup("cache"))
|
||
lbLimiter := NewRateLimiter()
|
||
// Cover Art Archive has its own rate limits, separate from LB.
|
||
// Allow 8 concurrent fetches so album art loads quickly.
|
||
caaLimiter := NewRateLimiterBurst(8, 8)
|
||
// MB search limiter: 3 tokens/sec, burst of 1. This spaces the
|
||
// three concurrent search goroutines ~333ms apart instead of
|
||
// firing all at once. MusicBrainz uses an all-or-nothing rate
|
||
// limit — exceeding 1/sec average causes 503 on ALL requests,
|
||
// which triggers the library's retry loop (up to 5 × 1s waits).
|
||
// Staggering avoids the 503 entirely while keeping total phase-1
|
||
// latency under 1.5s (333ms stagger + ~1s MB response).
|
||
mbSearchLimiter := NewRateLimiterBurst(3, 1)
|
||
// MB background limiter: strict 1/sec for sustained image resolution calls.
|
||
mbBackgroundLimiter := NewRateLimiter()
|
||
mb := NewMusicBrainzClient(cache, mbSearchLimiter, logger.WithGroup("musicbrainz"))
|
||
lb := NewListenBrainzClient(lbLimiter, cache, logger.WithGroup("listenbrainz"))
|
||
artProxy := NewCoverArtProxy(db, caaLimiter)
|
||
artistImg := NewArtistImageProvider(
|
||
db, cache, mbBackgroundLimiter, logger.WithGroup("artist-image"),
|
||
)
|
||
index := NewSearchIndex(db, lb, artistImg, logger.WithGroup("search-index"))
|
||
index.MarkReadyIfPopulated() // make index queryable immediately if data exists
|
||
libMBID := NewLibraryMBIDIndex(db)
|
||
|
||
logger.Info("explore service created")
|
||
|
||
return &Service{
|
||
mb: mb,
|
||
lb: lb,
|
||
cache: cache,
|
||
index: index,
|
||
artProxy: artProxy,
|
||
artistImg: artistImg,
|
||
libMBID: libMBID,
|
||
db: db,
|
||
logger: logger,
|
||
ctx: context.Background(),
|
||
}
|
||
}
|
||
|
||
// SetContext injects the Wails runtime context. Called from
|
||
// OnStartup after the Wails runtime is initialised.
|
||
func (e *Service) SetContext(ctx context.Context) {
|
||
e.ctx = ctx
|
||
e.index.SetContext(ctx)
|
||
}
|
||
|
||
// StartIndexBuild kicks off the background search index build.
|
||
// Call this after the library scan completes so the indexer doesn't
|
||
// starve the scan for DB access.
|
||
func (e *Service) StartIndexBuild() {
|
||
e.index.StartBuild(e.ctx)
|
||
}
|
||
|
||
// IndexNewArtists indexes only library artists not yet in the search
|
||
// index. Lightweight post-scan path — skips the full tier machinery.
|
||
func (e *Service) IndexNewArtists() {
|
||
e.index.IndexNewArtists(e.ctx)
|
||
}
|
||
|
||
// StopIndexBuild cancels the background search index build.
|
||
// Call before a full rescan to free the DB for the scan.
|
||
func (e *Service) StopIndexBuild() {
|
||
e.index.StopBuild()
|
||
}
|
||
|
||
// IsIndexReady returns true once the index has been populated.
|
||
func (e *Service) IsIndexReady() bool {
|
||
return e.index.IsReady()
|
||
}
|
||
|
||
// WaitForIndexIdle blocks until no index build or artist indexing
|
||
// goroutine is running. Does not cancel a running build.
|
||
func (e *Service) WaitForIndexIdle() {
|
||
e.index.WaitForIdle()
|
||
}
|
||
|
||
// PopulateLocalCrossReferences updates the local_*_id columns on
|
||
// explore_index after a library scan.
|
||
func (e *Service) PopulateLocalCrossReferences() {
|
||
e.index.PopulateLocalCrossReferences()
|
||
}
|
||
|
||
// GetIndexStatus returns the current search index build status.
|
||
func (e *Service) GetIndexStatus() IndexStatus {
|
||
return e.index.GetIndexStatus()
|
||
}
|
||
|
||
// InvalidateIndexDiscographies clears the discography build
|
||
// timestamp so the next index build re-runs Tiers 2-4. Call
|
||
// after a library rescan that may have populated new MBIDs.
|
||
func (e *Service) InvalidateIndexDiscographies() {
|
||
e.index.InvalidateDiscographies()
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// MusicBrainz search
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// SearchArtists queries MusicBrainz for artists matching the query.
|
||
func (e *Service) SearchArtists(query string) ([]MBArtist, error) {
|
||
artists, _, err := e.mb.SearchArtists(e.ctx, query, mbSearchLimit)
|
||
return artists, err
|
||
}
|
||
|
||
// SearchReleaseGroups queries MusicBrainz for release groups matching the query.
|
||
func (e *Service) SearchReleaseGroups(query string) ([]MBReleaseGroup, error) {
|
||
rgs, _, err := e.mb.SearchReleaseGroups(e.ctx, query, mbSearchLimit)
|
||
return rgs, err
|
||
}
|
||
|
||
// SearchRecordings queries MusicBrainz for recordings matching the query.
|
||
func (e *Service) SearchRecordings(query string) ([]MBRecording, error) {
|
||
recs, _, err := e.mb.SearchRecordings(e.ctx, query, mbSearchLimit)
|
||
return recs, err
|
||
}
|
||
|
||
// SearchLocal queries only the local FTS5 index and returns results
|
||
// instantly with no network calls. Returns nil if the index isn't
|
||
// ready. The frontend calls this in parallel with Search() to show
|
||
// instant results while the full pipeline runs.
|
||
func (e *Service) SearchLocal(query string) *MBSearchResult {
|
||
indexHits := e.index.Search(query, indexSearchLimit)
|
||
if len(indexHits) == 0 {
|
||
return nil
|
||
}
|
||
|
||
var result MBSearchResult
|
||
mergeIndexHits(&result, indexHits)
|
||
|
||
// Remove special-purpose artists from local results too.
|
||
if len(result.Artists) > 0 {
|
||
filtered := result.Artists[:0]
|
||
for _, a := range result.Artists {
|
||
if !mbSpecialPurposeArtists[a.MBID] {
|
||
filtered = append(filtered, a)
|
||
}
|
||
}
|
||
result.Artists = filtered
|
||
}
|
||
|
||
// Cap counts but skip the minBlendedScore filter — index hits
|
||
// use scalePopularity scores that shouldn't be compared to
|
||
// blended MB+LB scores.
|
||
if len(result.Artists) > maxResults {
|
||
result.Artists = result.Artists[:maxResults]
|
||
}
|
||
|
||
if len(result.ReleaseGroups) > maxResults {
|
||
result.ReleaseGroups = result.ReleaseGroups[:maxResults]
|
||
}
|
||
|
||
if len(result.Recordings) > maxResults {
|
||
result.Recordings = result.Recordings[:maxResults]
|
||
}
|
||
|
||
return &result
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// MusicBrainz lookup
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// LookupArtist fetches a single MusicBrainz artist by MBID.
|
||
// Checks the local index first — has name, type, country,
|
||
// disambiguation, sort_name for indexed artists. Falls back to
|
||
// MB API for unknown artists and backfills the index for next time.
|
||
func (e *Service) LookupArtist(mbid string) (*MBArtist, error) {
|
||
if indexed := e.index.LookupArtistByMBID(mbid); indexed != nil && indexed.Title != "" {
|
||
artist := &MBArtist{
|
||
MBID: mbid,
|
||
Name: indexed.Title,
|
||
SortName: indexed.SortName,
|
||
Type: indexed.ArtistType,
|
||
Country: indexed.Country,
|
||
Disambiguation: indexed.Disambiguation,
|
||
Popularity: indexed.Popularity,
|
||
HasPopularity: indexed.Popularity > 0,
|
||
ListenerCount: indexed.ListenerCount,
|
||
InLibrary: indexed.InLibrary || indexed.LocalArtistID > 0,
|
||
LocalID: indexed.LocalArtistID,
|
||
}
|
||
|
||
return artist, nil
|
||
}
|
||
|
||
return e.mb.LookupArtist(e.ctx, mbid)
|
||
}
|
||
|
||
// LookupReleaseGroup fetches a single MusicBrainz release group by MBID.
|
||
func (e *Service) LookupReleaseGroup(mbid string) (*MBReleaseGroup, error) {
|
||
// Try the index first — has title, type, secondary_types, date, artist.
|
||
if indexed := e.index.LookupReleaseGroupByMBID(mbid); indexed != nil && indexed.Title != "" {
|
||
var secondary []string
|
||
if indexed.SecondaryTypes != "" {
|
||
secondary = strings.Split(indexed.SecondaryTypes, ",")
|
||
}
|
||
|
||
rg := &MBReleaseGroup{
|
||
MBID: mbid,
|
||
Title: indexed.Title,
|
||
ArtistCredit: indexed.ArtistName,
|
||
Popularity: indexed.Popularity,
|
||
ListenerCount: indexed.ListenerCount,
|
||
PrimaryType: indexed.PrimaryType,
|
||
SecondaryTypes: secondary,
|
||
FirstReleaseDate: indexed.ReleaseDate,
|
||
InLibrary: indexed.InLibrary || indexed.LocalReleaseGroupID > 0,
|
||
LocalID: indexed.LocalReleaseGroupID,
|
||
}
|
||
|
||
// Background: fetch full MB data if secondary_types is empty.
|
||
// After the first visit this will populate on the next request.
|
||
if indexed.SecondaryTypes == "" {
|
||
go func() {
|
||
_, _ = e.mb.LookupReleaseGroup(e.ctx, mbid)
|
||
}()
|
||
}
|
||
|
||
return rg, nil
|
||
}
|
||
|
||
return e.mb.LookupReleaseGroup(e.ctx, mbid)
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// MusicBrainz browse
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// BrowseReleaseGroups fetches release groups for a given artist MBID.
|
||
// Checks the local index first for instant results, then fetches from
|
||
// MusicBrainz for complete data (secondary types, precise dates).
|
||
// Also adds results to the search index (Tier 5: organic growth).
|
||
func (e *Service) BrowseReleaseGroups(artistMBID string) ([]MBReleaseGroup, error) {
|
||
// Try the index first — returns instantly if the artist is indexed.
|
||
if indexed := e.index.TopReleaseGroupsByArtist(artistMBID, 200); len(indexed) > 0 {
|
||
out := make([]MBReleaseGroup, 0, len(indexed))
|
||
|
||
// Check if ANY row has secondary types — if none do, we need
|
||
// to refresh from MB to pick them up. This typically happens
|
||
// on the first visit after an artist's discography was indexed
|
||
// from the LB top-release-groups endpoint (which doesn't
|
||
// return secondary types).
|
||
hasSecondaryTypes := false
|
||
|
||
for _, r := range indexed {
|
||
var secondary []string
|
||
if r.SecondaryTypes != "" {
|
||
secondary = strings.Split(r.SecondaryTypes, ",")
|
||
hasSecondaryTypes = true
|
||
}
|
||
|
||
out = append(out, MBReleaseGroup{
|
||
MBID: r.MBID,
|
||
Title: r.Title,
|
||
ArtistCredit: r.ArtistName,
|
||
Popularity: r.Popularity,
|
||
ListenerCount: r.ListenerCount,
|
||
PrimaryType: r.PrimaryType,
|
||
SecondaryTypes: secondary,
|
||
FirstReleaseDate: r.ReleaseDate,
|
||
InLibrary: r.InLibrary || r.LocalReleaseGroupID > 0,
|
||
LocalID: r.LocalReleaseGroupID,
|
||
})
|
||
}
|
||
|
||
// Fire MB browse in background if we're missing secondary types
|
||
// so the next visit gets them.
|
||
if !hasSecondaryTypes {
|
||
go func() {
|
||
rgs, err := e.mb.BrowseReleaseGroups(e.ctx, artistMBID)
|
||
if err == nil && len(rgs) > 0 {
|
||
artistName := e.resolveArtistName(artistMBID, rgs)
|
||
e.index.AddFromCache(artistName, artistMBID, rgs)
|
||
}
|
||
}()
|
||
}
|
||
|
||
return out, nil
|
||
}
|
||
|
||
rgs, err := e.mb.BrowseReleaseGroups(e.ctx, artistMBID)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
// Tier 5: organic growth — index this discography.
|
||
artistName := e.resolveArtistName(artistMBID, rgs)
|
||
|
||
go e.index.AddFromCache(artistName, artistMBID, rgs)
|
||
|
||
return rgs, nil
|
||
}
|
||
|
||
// resolveArtistName picks the best available artist name for a list
|
||
// of release groups returned from MB browse-by-artist. MB browse
|
||
// doesn't echo back the artist credit on each item (since the artist
|
||
// is the query parameter), so we need to find a name from somewhere:
|
||
// 1. First non-empty ArtistCredit on any release group
|
||
// 2. The local explore_index (if the artist was previously indexed)
|
||
// 3. A LookupArtist call to MB (last resort)
|
||
// 4. The MBID itself (worst case fallback)
|
||
func (e *Service) resolveArtistName(artistMBID string, rgs []MBReleaseGroup) string {
|
||
// Try first non-empty ArtistCredit from the release groups.
|
||
for _, rg := range rgs {
|
||
if rg.ArtistCredit != "" {
|
||
return rg.ArtistCredit
|
||
}
|
||
}
|
||
|
||
// Check the index for a previously-indexed artist row.
|
||
if indexed := e.index.LookupArtistByMBID(artistMBID); indexed != nil && indexed.Title != "" && indexed.Title != artistMBID {
|
||
return indexed.Title
|
||
}
|
||
|
||
// Last resort: hit MB lookup.
|
||
if artist, err := e.mb.LookupArtist(e.ctx, artistMBID); err == nil && artist != nil && artist.Name != "" {
|
||
return artist.Name
|
||
}
|
||
|
||
return artistMBID
|
||
}
|
||
|
||
// BrowseReleases fetches releases for a given release group MBID.
|
||
func (e *Service) BrowseReleases(releaseGroupMBID string) ([]MBRelease, error) {
|
||
releases, err := e.mb.BrowseReleases(e.ctx, releaseGroupMBID)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
// Collect all recording MBIDs across all releases and check them
|
||
// against the local library in a single query. Populates the
|
||
// InLibrary flag on each track so the tracklist renderer can
|
||
// show the library-status indicator without a per-track roundtrip.
|
||
var trackMBIDs []string
|
||
for _, rel := range releases {
|
||
for _, t := range rel.Tracks {
|
||
if t.MBID != "" {
|
||
trackMBIDs = append(trackMBIDs, t.MBID)
|
||
}
|
||
}
|
||
}
|
||
|
||
if len(trackMBIDs) > 0 {
|
||
found := e.libMBID.CheckMBIDs(trackMBIDs)
|
||
|
||
for i := range releases {
|
||
for j := range releases[i].Tracks {
|
||
mbid := releases[i].Tracks[j].MBID
|
||
if _, ok := found[mbid]; ok {
|
||
releases[i].Tracks[j].InLibrary = true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
return releases, nil
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// ListenBrainz
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// TopRecordingsForArtist returns the most-listened recordings for an artist.
|
||
func (e *Service) TopRecordingsForArtist(artistMBID string) ([]LBTopRecording, error) {
|
||
// Try the local index first (instant, no API call).
|
||
if indexed := e.index.TopRecordingsByArtist(artistMBID, 50); len(indexed) > 0 {
|
||
out := make([]LBTopRecording, len(indexed))
|
||
for i, r := range indexed {
|
||
out[i] = LBTopRecording{
|
||
RecordingMBID: r.MBID,
|
||
ArtistName: r.ArtistName,
|
||
TrackName: r.Title,
|
||
TotalListenCount: r.Popularity,
|
||
CAAReleaseMBID: r.CAAReleaseMBID,
|
||
ReleaseName: r.ReleaseName,
|
||
Length: r.Duration,
|
||
InLibrary: r.InLibrary || r.LocalRecordingID > 0,
|
||
LocalID: r.LocalRecordingID,
|
||
}
|
||
}
|
||
|
||
return out, nil
|
||
}
|
||
|
||
// Fall back to LB API.
|
||
return e.lb.TopRecordingsForArtist(e.ctx, artistMBID)
|
||
}
|
||
|
||
// TopReleaseGroupsForArtist returns the most-listened release groups for an artist.
|
||
func (e *Service) TopReleaseGroupsForArtist(artistMBID string) ([]LBTopReleaseGroup, error) {
|
||
// Try the local index first (instant, no API call).
|
||
if indexed := e.index.TopReleaseGroupsByArtist(artistMBID, 50); len(indexed) > 0 {
|
||
out := make([]LBTopReleaseGroup, len(indexed))
|
||
for i, r := range indexed {
|
||
out[i] = LBTopReleaseGroup{
|
||
ReleaseGroupMBID: r.MBID,
|
||
Title: r.Title,
|
||
ArtistName: r.ArtistName,
|
||
TotalListenCount: r.Popularity,
|
||
Type: r.PrimaryType,
|
||
Date: r.ReleaseDate,
|
||
CAAReleaseMBID: r.CAAReleaseMBID,
|
||
InLibrary: r.InLibrary || r.LocalReleaseGroupID > 0,
|
||
LocalID: r.LocalReleaseGroupID,
|
||
}
|
||
}
|
||
|
||
return out, nil
|
||
}
|
||
|
||
// Fall back to LB API.
|
||
return e.lb.TopReleaseGroupsForArtist(e.ctx, artistMBID)
|
||
}
|
||
|
||
// SimilarArtists returns artists similar to the given artist MBID.
|
||
func (e *Service) SimilarArtists(artistMBID string) ([]LBSimilarArtist, error) {
|
||
// Try the pre-computed similar_artist_map first (instant, no API call).
|
||
// This is populated during Tier 4 for library artists and their network.
|
||
rows, err := e.db.QueryContext(`
|
||
SELECT similar_artist_mbid, similar_artist_name, score
|
||
FROM similar_artist_map
|
||
WHERE source_artist_mbid = ?
|
||
ORDER BY score DESC
|
||
`, artistMBID)
|
||
if err == nil {
|
||
defer func() { _ = rows.Close() }()
|
||
|
||
var results []LBSimilarArtist
|
||
|
||
for rows.Next() {
|
||
var a LBSimilarArtist
|
||
if err := rows.Scan(&a.ArtistMBID, &a.Name, &a.Score); err == nil {
|
||
results = append(results, a)
|
||
}
|
||
}
|
||
|
||
if len(results) > 0 {
|
||
return results, nil
|
||
}
|
||
}
|
||
|
||
// Fall back to LB labs API.
|
||
return e.lb.SimilarArtists(e.ctx, artistMBID)
|
||
}
|
||
|
||
// GetArtistPlayCount returns the total LB listen count for an artist.
|
||
// Returns 0 if unknown.
|
||
func (e *Service) GetArtistPlayCount(artistMBID string) int {
|
||
// Try the local index first (instant).
|
||
if pop := e.index.GetPopularity(artistMBID); pop > 0 {
|
||
return pop
|
||
}
|
||
|
||
// Fall back to LB API.
|
||
pop, err := e.lb.ArtistPopularity(e.ctx, []string{artistMBID})
|
||
if err != nil || len(pop) == 0 {
|
||
return 0
|
||
}
|
||
|
||
// Backfill index for next time.
|
||
go e.index.BackfillPopularity(pop)
|
||
|
||
return pop[artistMBID].ListenCount
|
||
}
|
||
|
||
// GetLibrarySimilarArtists returns similar artists to the given
|
||
// MBID that are also in the user's local library. Uses the
|
||
// pre-computed similar_artist_map table (populated during Tier 4
|
||
// index build) joined with the artists table. No API calls.
|
||
//
|
||
// The artists table allows multiple rows with the same MBID
|
||
// (different artist credits like "A feat. B" that resolve to the
|
||
// same MB artist), so we use EXISTS instead of JOIN to avoid
|
||
// duplicating similar_artist_map rows.
|
||
func (e *Service) GetLibrarySimilarArtists(artistMBID string) []LBSimilarArtist {
|
||
rows, err := e.db.QueryContext(`
|
||
SELECT s.similar_artist_mbid, s.similar_artist_name, s.score
|
||
FROM similar_artist_map s
|
||
WHERE s.source_artist_mbid = ?
|
||
AND EXISTS (
|
||
SELECT 1 FROM artists a
|
||
WHERE a.mbid = s.similar_artist_mbid
|
||
)
|
||
ORDER BY s.score DESC
|
||
`, artistMBID)
|
||
if err != nil {
|
||
return nil
|
||
}
|
||
|
||
defer func() { _ = rows.Close() }()
|
||
|
||
var result []LBSimilarArtist
|
||
|
||
for rows.Next() {
|
||
var a LBSimilarArtist
|
||
|
||
if err := rows.Scan(&a.ArtistMBID, &a.Name, &a.Score); err == nil {
|
||
result = append(result, a)
|
||
}
|
||
}
|
||
|
||
return result
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Cover Art Archive
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// CoverArtURL returns the Cover Art Archive URL for a release's
|
||
// front cover at the default 250px size.
|
||
func (e *Service) CoverArtURL(releaseMBID string) string {
|
||
return CoverArtURL(releaseMBID)
|
||
}
|
||
|
||
// CoverArtGroupURL returns the Cover Art Archive URL for a release
|
||
// group's front cover at the default 250px size. This is the
|
||
// correct endpoint for search results, which return release group
|
||
// MBIDs rather than individual release MBIDs.
|
||
func (e *Service) CoverArtGroupURL(releaseGroupMBID string) string {
|
||
return CoverArtGroupURL(releaseGroupMBID)
|
||
}
|
||
|
||
// GetThumbnail returns a base64 data URL for the release group's
|
||
// cover art. Checks local library art first (by album+artist
|
||
// name), then disk cache, then Cover Art Archive.
|
||
// Returns "" if no cover art is available.
|
||
func (e *Service) GetThumbnail(releaseGroupMBID, albumName, artistName string) string {
|
||
return e.artProxy.GetThumbnail(releaseGroupMBID, albumName, artistName)
|
||
}
|
||
|
||
// GetTrackThumbnail returns cover art for a track. Accepts both
|
||
// the track's CAA release MBID and the resolved parent release
|
||
// group MBID (either may be empty). Tries the RG first to reuse
|
||
// discography cache; falls back to the release-level CAA endpoint
|
||
// when the RG isn't known — useful when the track's preferred CAA
|
||
// release doesn't belong to any RG currently in the index.
|
||
func (e *Service) GetTrackThumbnail(releaseMBID, releaseGroupMBID, albumName, artistName string) string {
|
||
return e.artProxy.GetTrackThumbnail(releaseMBID, releaseGroupMBID, albumName, artistName)
|
||
}
|
||
|
||
// TrackThumbnailRequest is a single item in a batch track thumbnail
|
||
// request. Either ReleaseMBID or ReleaseGroupMBID may be empty;
|
||
// the proxy tries whichever is present.
|
||
type TrackThumbnailRequest struct {
|
||
Key string `json:"key"` // stable key used in the returned map
|
||
ReleaseMBID string `json:"releaseMbid"`
|
||
ReleaseGroupMBID string `json:"releaseGroupMbid"`
|
||
AlbumName string `json:"albumName"`
|
||
ArtistName string `json:"artistName"`
|
||
}
|
||
|
||
// GetTrackThumbnails returns ONLY cached/local art for track
|
||
// requests, keyed by the caller-provided Key so callers can map
|
||
// results back to rows in their UI.
|
||
func (e *Service) GetTrackThumbnails(requests []TrackThumbnailRequest) map[string]string {
|
||
result := make(map[string]string, len(requests))
|
||
|
||
for _, req := range requests {
|
||
dataURL := e.artProxy.GetTrackThumbnailCached(
|
||
req.ReleaseMBID, req.ReleaseGroupMBID, req.AlbumName, req.ArtistName,
|
||
)
|
||
if dataURL != "" {
|
||
result[req.Key] = dataURL
|
||
}
|
||
}
|
||
|
||
return result
|
||
}
|
||
|
||
// ResolveReleaseGroupMBIDs takes a list of CAA release MBIDs (from
|
||
// recording metadata) and returns a map of release MBID → release
|
||
// group MBID. The frontend uses this to fetch track cover art via
|
||
// the parent release group, reusing whatever cache exists for the
|
||
// album already.
|
||
func (e *Service) ResolveReleaseGroupMBIDs(caaReleaseMBIDs []string) map[string]string {
|
||
return e.index.ReleaseGroupMBIDsForCAAReleaseMBIDs(caaReleaseMBIDs)
|
||
}
|
||
|
||
// ThumbnailRequest is a single item in a batch thumbnail request.
|
||
type ThumbnailRequest struct {
|
||
MBID string `json:"mbid"`
|
||
AlbumName string `json:"albumName"`
|
||
ArtistName string `json:"artistName"`
|
||
}
|
||
|
||
// GetThumbnails fetches multiple thumbnails in one call and returns
|
||
// a map of MBID → base64 data URL. Entries with no art are omitted.
|
||
// GetThumbnails returns ONLY cached/local art instantly — no network
|
||
// fetches. For items missing from the cache, the frontend should
|
||
// call GetThumbnail() individually so results stream in rather than
|
||
// blocking on a batch.
|
||
func (e *Service) GetThumbnails(requests []ThumbnailRequest) map[string]string {
|
||
result := make(map[string]string, len(requests))
|
||
|
||
for _, req := range requests {
|
||
dataURL := e.artProxy.GetThumbnailCached(req.MBID, req.AlbumName, req.ArtistName)
|
||
if dataURL != "" {
|
||
result[req.MBID] = dataURL
|
||
}
|
||
}
|
||
|
||
return result
|
||
}
|
||
|
||
// GetArtistImageURL returns a base64 data URL for the artist's
|
||
// photo. Cached on disk — first call resolves via MB/Wikidata and
|
||
// fetches from Wikimedia Commons, subsequent calls are instant.
|
||
// Returns "" if no image is available.
|
||
func (e *Service) GetArtistImageURL(artistMBID string) string {
|
||
return e.artistImg.GetArtistImage(artistMBID)
|
||
}
|
||
|
||
// GetArtistImageCached returns a base64 data URL for the artist's
|
||
// photo ONLY if it's already on disk — no MB/Wikidata resolution
|
||
// or Wikimedia fetch. Safe to call from library-only mode.
|
||
// Returns "" if not cached.
|
||
func (e *Service) GetArtistImageCached(artistMBID string) string {
|
||
return e.artistImg.GetCachedImage(artistMBID)
|
||
}
|
||
|
||
// GetArtistImageCachedPath returns the asset-handler URL path for
|
||
// the artist's cached medium thumbnail, e.g.
|
||
// "/artist-images/b1/b10bbbfc-.../primary_md.jpg". No base64, no
|
||
// network calls — just a disk existence check. Returns "" if no
|
||
// image is cached.
|
||
func (e *Service) GetArtistImageCachedPath(artistMBID string) string {
|
||
_, medium, _, _ := e.artistImg.GetImageURLs(artistMBID)
|
||
return medium
|
||
}
|
||
|
||
// CheckLibraryMBIDs returns which of the given MBIDs exist in the
|
||
// local music library. Returns a map of MBID → entity type
|
||
// ("artist", "release_group", "recording").
|
||
func (e *Service) CheckLibraryMBIDs(mbids []string) map[string]string {
|
||
return e.libMBID.CheckMBIDs(mbids)
|
||
}
|
||
|
||
// PersonalizationResult holds popularity and personalization signals
|
||
// for a single MBID. Exported for Wails binding.
|
||
type PersonalizationResult struct {
|
||
Popularity int `json:"popularity"`
|
||
ListenerCount int `json:"listenerCount"`
|
||
InLibrary bool `json:"inLibrary"`
|
||
SimilarityScore int `json:"similarityScore"`
|
||
}
|
||
|
||
// GetPopularityBatch returns LB popularity and personalization
|
||
// signals for a batch of MBIDs from the local search index.
|
||
func (e *Service) GetPopularityBatch(mbids []string) map[string]PersonalizationResult {
|
||
batch := e.index.GetPopularityBatch(mbids)
|
||
if batch == nil {
|
||
return make(map[string]PersonalizationResult)
|
||
}
|
||
|
||
out := make(map[string]PersonalizationResult, len(batch.Popularity))
|
||
for mbid, pop := range batch.Popularity {
|
||
out[mbid] = PersonalizationResult{
|
||
Popularity: pop,
|
||
ListenerCount: batch.ListenerCount[mbid],
|
||
InLibrary: batch.InLibrary[mbid],
|
||
SimilarityScore: batch.SimilarityScores[mbid],
|
||
}
|
||
}
|
||
|
||
// Include entries that have library/similar flags but no popularity.
|
||
for mbid := range batch.InLibrary {
|
||
if _, ok := out[mbid]; !ok {
|
||
out[mbid] = PersonalizationResult{InLibrary: true, SimilarityScore: batch.SimilarityScores[mbid]}
|
||
}
|
||
}
|
||
|
||
for mbid, score := range batch.SimilarityScores {
|
||
if _, ok := out[mbid]; !ok {
|
||
out[mbid] = PersonalizationResult{SimilarityScore: score}
|
||
}
|
||
}
|
||
|
||
return out
|
||
}
|
||
|
||
// GetArtistMBID returns the MusicBrainz ID for a local library
|
||
// artist by name, or "" if not found or no MBID tagged.
|
||
func (e *Service) GetArtistMBID(artistName string) string {
|
||
return e.libMBID.GetArtistMBID(artistName)
|
||
}
|
||
|
||
// GetArtistImages resolves artist images for multiple artists by
|
||
// name in one call. Returns a map of artist name → base64 data
|
||
// URL. Only artists with cached images are returned — no network
|
||
// fetches are triggered (use GetArtistImageURL for on-demand fetch).
|
||
func (e *Service) GetArtistImages(names []string) map[string]string {
|
||
result := make(map[string]string, len(names))
|
||
|
||
// Batch resolve all names → MBIDs from the library DB.
|
||
allMBIDs := e.libMBID.AllArtistMBIDs()
|
||
|
||
for _, name := range names {
|
||
mbid, ok := allMBIDs[name]
|
||
if !ok || mbid == "" {
|
||
continue
|
||
}
|
||
|
||
// Only return already-cached images — don't trigger fetches.
|
||
img := e.artistImg.GetCachedImage(mbid)
|
||
if img != "" {
|
||
result[name] = img
|
||
}
|
||
}
|
||
|
||
return result
|
||
}
|
||
|
||
// Search concurrently queries MusicBrainz for artists, release
|
||
// groups, and recordings matching the query, then boosts results
|
||
// using ListenBrainz popularity data. The final score blends
|
||
// text relevance (60%) with log-scaled listen counts (40%).
|
||
//
|
||
// If any sub-search or popularity lookup fails the error is logged
|
||
// and the remaining results are still returned — popularity
|
||
// failures degrade to MB-only ordering.
|
||
func (e *Service) Search(query string) (*MBSearchResult, error) {
|
||
searchStart := time.Now()
|
||
|
||
// Build the Lucene query: AND terms with wildcard on last.
|
||
luceneQuery := buildLuceneQuery(query)
|
||
// For RGs, also search by artist credit so that "queen" returns
|
||
// albums BY Queen, not just titles containing "queen".
|
||
rgQuery := buildLuceneQueryWithArtist(query, "releasegroup", "artist")
|
||
// Recordings search by title only — the OR with artist caused
|
||
// double-match inflation where tracks by "Queen" with "queen" in
|
||
// the title got artificially boosted over more popular results.
|
||
// The local index handles artist→recording discovery via
|
||
// popularity-weighted FTS across title + artist_name + aliases.
|
||
recQuery := buildLuceneQuery(query)
|
||
|
||
e.logger.Info("search started", "query", query, "lucene", luceneQuery)
|
||
|
||
// Phase 0: query local popularity index (instant, no API calls).
|
||
p0Start := time.Now()
|
||
indexHits := e.index.Search(query, indexSearchLimit) //nolint:mnd
|
||
p0Dur := time.Since(p0Start)
|
||
|
||
e.logger.Info("search phase 0 complete (index)",
|
||
"query", query,
|
||
"hits", len(indexHits),
|
||
"elapsed", p0Dur,
|
||
)
|
||
|
||
// Phase 1: concurrent MB search (3 goroutines) with a deadline
|
||
// so a slow MusicBrainz server doesn't hold up the whole search.
|
||
//
|
||
// First pass uses a small limit to discover total match counts.
|
||
// If MB reports many matches, a second pass re-fetches with a
|
||
// larger limit so the ranking pipeline has better material.
|
||
p1Start := time.Now()
|
||
|
||
mbCtx, mbCancel := context.WithTimeout(e.ctx, searchMBTimeout)
|
||
defer mbCancel()
|
||
|
||
var (
|
||
result MBSearchResult
|
||
mu sync.Mutex
|
||
wg sync.WaitGroup
|
||
)
|
||
|
||
type mbInitial struct {
|
||
artists []MBArtist
|
||
rgs []MBReleaseGroup
|
||
recordings []MBRecording
|
||
artistN int
|
||
rgN int
|
||
recN int
|
||
}
|
||
|
||
var initial mbInitial
|
||
|
||
type searchFunc struct {
|
||
name string
|
||
fn func()
|
||
}
|
||
|
||
searches := []searchFunc{
|
||
{
|
||
name: "artists",
|
||
fn: func() {
|
||
t := time.Now()
|
||
artists, total, err := e.mb.SearchArtists(mbCtx, luceneQuery, mbSearchLimit)
|
||
|
||
e.logger.Info("search MB sub-call",
|
||
"entity", "artists",
|
||
"elapsed", time.Since(t).Round(time.Millisecond),
|
||
"results", len(artists),
|
||
"totalMatches", total,
|
||
"cached", err == nil && time.Since(t) < 5*time.Millisecond,
|
||
)
|
||
|
||
if err != nil {
|
||
e.logger.Warn("search sub-call failed",
|
||
"entity", "artists",
|
||
"query", query,
|
||
"error", err,
|
||
)
|
||
|
||
return
|
||
}
|
||
|
||
mu.Lock()
|
||
initial.artists = artists
|
||
initial.artistN = total
|
||
mu.Unlock()
|
||
},
|
||
},
|
||
{
|
||
name: "releaseGroups",
|
||
fn: func() {
|
||
t := time.Now()
|
||
rgs, total, err := e.mb.SearchReleaseGroups(mbCtx, rgQuery, mbSearchLimit)
|
||
|
||
e.logger.Info("search MB sub-call",
|
||
"entity", "releaseGroups",
|
||
"elapsed", time.Since(t).Round(time.Millisecond),
|
||
"results", len(rgs),
|
||
"totalMatches", total,
|
||
"cached", err == nil && time.Since(t) < 5*time.Millisecond,
|
||
)
|
||
|
||
if err != nil {
|
||
e.logger.Warn("search sub-call failed",
|
||
"entity", "releaseGroups",
|
||
"query", query,
|
||
"error", err,
|
||
)
|
||
|
||
return
|
||
}
|
||
|
||
mu.Lock()
|
||
initial.rgs = rgs
|
||
initial.rgN = total
|
||
mu.Unlock()
|
||
},
|
||
},
|
||
{
|
||
name: "recordings",
|
||
fn: func() {
|
||
t := time.Now()
|
||
recs, total, err := e.mb.SearchRecordings(mbCtx, recQuery, mbSearchLimit)
|
||
|
||
e.logger.Info("search MB sub-call",
|
||
"entity", "recordings",
|
||
"elapsed", time.Since(t).Round(time.Millisecond),
|
||
"results", len(recs),
|
||
"totalMatches", total,
|
||
"cached", err == nil && time.Since(t) < 5*time.Millisecond,
|
||
)
|
||
|
||
if err != nil {
|
||
e.logger.Warn("search sub-call failed",
|
||
"entity", "recordings",
|
||
"query", query,
|
||
"error", err,
|
||
)
|
||
|
||
return
|
||
}
|
||
|
||
mu.Lock()
|
||
initial.recordings = recs
|
||
initial.recN = total
|
||
mu.Unlock()
|
||
},
|
||
},
|
||
}
|
||
|
||
wg.Add(len(searches))
|
||
|
||
for _, s := range searches {
|
||
go func() {
|
||
defer wg.Done()
|
||
|
||
s.fn()
|
||
}()
|
||
}
|
||
|
||
wg.Wait()
|
||
|
||
result.Artists = initial.artists
|
||
result.ReleaseGroups = initial.rgs
|
||
result.Recordings = initial.recordings
|
||
|
||
p1Dur := time.Since(p1Start)
|
||
|
||
e.logger.Info("search phase 1 complete (MB)",
|
||
"query", query,
|
||
"artists", len(result.Artists),
|
||
"releaseGroups", len(result.ReleaseGroups),
|
||
"recordings", len(result.Recordings),
|
||
"expanded", len(result.Artists) > mbSearchLimit || len(result.ReleaseGroups) > mbSearchLimit || len(result.Recordings) > mbSearchLimit,
|
||
"elapsed", p1Dur.Round(time.Millisecond),
|
||
)
|
||
|
||
// Phases 2+3: when the index is ready, use cached popularity
|
||
// from the index to rerank MB results (no API calls).
|
||
// When the index isn't ready, fall back to live LB API calls.
|
||
p2Start := time.Now()
|
||
indexReady := e.index.IsReady()
|
||
|
||
// Phase 2a: resolve artist popularity and library membership.
|
||
artistMBIDs := make([]string, 0, len(result.Artists))
|
||
for _, a := range result.Artists {
|
||
if a.MBID != "" {
|
||
artistMBIDs = append(artistMBIDs, a.MBID)
|
||
}
|
||
}
|
||
|
||
artistPop := make(map[string]int)
|
||
libMBIDs := make(map[string]bool)
|
||
simScores := make(map[string]int)
|
||
|
||
if indexReady {
|
||
// Fast path: use local index data only — no API call.
|
||
// The batch includes popularity, in_library, and similarity scores.
|
||
batch := e.index.GetPopularityBatch(artistMBIDs)
|
||
if batch != nil {
|
||
for mbid, pop := range batch.Popularity {
|
||
artistPop[mbid] = pop
|
||
}
|
||
|
||
libMBIDs = batch.InLibrary
|
||
simScores = batch.SimilarityScores
|
||
}
|
||
|
||
// Fill in missing artist popularity from LB synchronously
|
||
// (with a tight timeout). Without this, artists not yet
|
||
// indexed get popularity 0 and the rerank can't
|
||
// differentiate them from each other, producing nonsense
|
||
// ordering for result sets where MB gave every candidate
|
||
// the same text relevance score.
|
||
var missingPop []string
|
||
for _, mbid := range artistMBIDs {
|
||
if artistPop[mbid] <= 0 {
|
||
missingPop = append(missingPop, mbid)
|
||
}
|
||
}
|
||
|
||
if len(missingPop) > 0 {
|
||
popCtx, popCancel := context.WithTimeout(e.ctx, searchSlowPathTimeout)
|
||
|
||
pop, err := e.lb.ArtistPopularity(popCtx, missingPop)
|
||
popCancel()
|
||
|
||
if err == nil && pop != nil {
|
||
for mbid, data := range pop {
|
||
if data.ListenCount > 0 {
|
||
artistPop[mbid] = data.ListenCount
|
||
}
|
||
}
|
||
|
||
go e.index.BackfillPopularity(pop)
|
||
}
|
||
}
|
||
} else {
|
||
// Slow path: fetch from LB API with a tight timeout
|
||
// so a hung LB server doesn't stall the search.
|
||
popCtx, popCancel := context.WithTimeout(e.ctx, 2*time.Second)
|
||
pop, _ := e.lb.ArtistPopularity(popCtx, artistMBIDs)
|
||
popCancel()
|
||
|
||
if pop != nil {
|
||
artistPop = listenCounts(pop)
|
||
|
||
go e.index.BackfillPopularity(pop)
|
||
}
|
||
|
||
// Still need library/similar membership from the index.
|
||
batch := e.index.GetPopularityBatch(artistMBIDs)
|
||
if batch != nil {
|
||
libMBIDs = batch.InLibrary
|
||
simScores = batch.SimilarityScores
|
||
}
|
||
}
|
||
|
||
// Mark popularity and library status on artists for downstream use.
|
||
for i := range result.Artists {
|
||
if pop, ok := artistPop[result.Artists[i].MBID]; ok && pop > 0 {
|
||
result.Artists[i].HasPopularity = true
|
||
result.Artists[i].Popularity = pop
|
||
}
|
||
|
||
if libMBIDs[result.Artists[i].MBID] {
|
||
result.Artists[i].InLibrary = true
|
||
}
|
||
}
|
||
|
||
rerankArtistsPersonalized(result.Artists, artistPop, libMBIDs, simScores)
|
||
|
||
// Phase 2b: rerank release groups and recordings.
|
||
if indexReady {
|
||
e.boostWithIndexPopularityRGsAndRecs(&result)
|
||
} else {
|
||
// Slow path: LB popularity + cross-reference in parallel.
|
||
slowCtx, slowCancel := context.WithTimeout(e.ctx, searchSlowPathTimeout)
|
||
|
||
var wgSlow sync.WaitGroup
|
||
wgSlow.Add(2) //nolint:mnd
|
||
|
||
// Leg 1: LB popularity for RGs and recordings.
|
||
go func() {
|
||
defer wgSlow.Done()
|
||
e.boostWithPopularityRGsAndRecs(&result)
|
||
}()
|
||
|
||
// Leg 2: cross-reference artist discographies.
|
||
go func() {
|
||
defer wgSlow.Done()
|
||
if slowCtx.Err() == nil {
|
||
e.crossReferenceAlbums(slowCtx, query, &result)
|
||
}
|
||
}()
|
||
|
||
wgSlow.Wait()
|
||
slowCancel()
|
||
}
|
||
|
||
p2Dur := time.Since(p2Start)
|
||
|
||
e.logger.Info("search phase 2-3 complete (rerank)",
|
||
"query", query,
|
||
"indexReady", indexReady,
|
||
"elapsed", p2Dur.Round(time.Millisecond),
|
||
)
|
||
|
||
// Phase 4: merge local index hits into results, dedup by MBID.
|
||
mergeIndexHits(&result, indexHits)
|
||
|
||
// Phase 5: boost exact/substring name matches so a search for
|
||
// "the teenagers" ranks "The Teenagers" above "The Beatles"
|
||
// even when The Beatles have vastly more listens.
|
||
e.boostNameMatches(query, &result)
|
||
|
||
// Phase 6: filter low-scoring results and cap counts.
|
||
filterAndCap(&result)
|
||
|
||
// Phase 7: resolve top result cards via intent scoring.
|
||
result.TopResults = e.resolveTopResults(query, &result)
|
||
|
||
totalDur := time.Since(searchStart)
|
||
|
||
e.logger.Info("search completed",
|
||
"query", query,
|
||
"artists", len(result.Artists),
|
||
"releaseGroups", len(result.ReleaseGroups),
|
||
"recordings", len(result.Recordings),
|
||
"total", totalDur.Round(time.Millisecond),
|
||
"phase0", p0Dur.Round(time.Millisecond),
|
||
"phase1_mb", p1Dur.Round(time.Millisecond),
|
||
"phase2_rerank", p2Dur.Round(time.Millisecond),
|
||
)
|
||
|
||
return &result, nil
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Cross-reference search
|
||
// ---------------------------------------------------------------------------
|
||
|
||
const (
|
||
// crossRefArtists is the number of top artists whose
|
||
// discographies are searched for matching albums.
|
||
crossRefArtists = 3
|
||
|
||
// crossRefMinRatio is the minimum fuzzy match ratio (0–1)
|
||
// for an album title to be considered a match.
|
||
crossRefMinRatio = 0.4
|
||
)
|
||
|
||
// crossReferenceAlbums browses the discographies of the top N
|
||
// artists and fuzzy-matches the query against album titles.
|
||
// Matched albums not already in result.ReleaseGroups are injected
|
||
// at the front. This handles queries like "for you tatsuro"
|
||
// where MB text search can't associate the title with the artist.
|
||
func (e *Service) crossReferenceAlbums(ctx context.Context, query string, result *MBSearchResult) {
|
||
if len(result.Artists) == 0 {
|
||
return
|
||
}
|
||
|
||
limit := crossRefArtists
|
||
if limit > len(result.Artists) {
|
||
limit = len(result.Artists)
|
||
}
|
||
|
||
topArtists := result.Artists[:limit]
|
||
queryLower := strings.ToLower(strings.TrimSpace(query))
|
||
|
||
// Build a set of release group MBIDs already in results.
|
||
existing := make(map[string]bool, len(result.ReleaseGroups))
|
||
for _, rg := range result.ReleaseGroups {
|
||
existing[rg.MBID] = true
|
||
}
|
||
|
||
// Browse discographies concurrently.
|
||
type match struct {
|
||
rg MBReleaseGroup
|
||
ratio float64
|
||
}
|
||
|
||
var (
|
||
matches []match
|
||
mu sync.Mutex
|
||
wg sync.WaitGroup
|
||
)
|
||
|
||
wg.Add(limit)
|
||
|
||
for _, artist := range topArtists {
|
||
go func(a MBArtist) {
|
||
defer wg.Done()
|
||
|
||
rgs, err := e.mb.BrowseReleaseGroups(ctx, a.MBID)
|
||
if err != nil {
|
||
e.logger.Warn("cross-reference browse failed",
|
||
"artist", a.Name,
|
||
"mbid", a.MBID,
|
||
"error", err,
|
||
)
|
||
|
||
return
|
||
}
|
||
|
||
for _, rg := range rgs {
|
||
if existing[rg.MBID] {
|
||
continue
|
||
}
|
||
|
||
ratio := fuzzyMatchRatio(queryLower, strings.ToLower(rg.Title))
|
||
if ratio >= crossRefMinRatio {
|
||
mu.Lock()
|
||
|
||
matches = append(matches, match{rg: rg, ratio: ratio})
|
||
|
||
mu.Unlock()
|
||
}
|
||
}
|
||
}(artist)
|
||
}
|
||
|
||
wg.Wait()
|
||
|
||
if len(matches) == 0 {
|
||
return
|
||
}
|
||
|
||
// Sort by match ratio descending.
|
||
sort.SliceStable(matches, func(i, j int) bool {
|
||
return matches[i].ratio > matches[j].ratio
|
||
})
|
||
|
||
// Inject at the front of release groups.
|
||
injected := make([]MBReleaseGroup, 0, len(matches))
|
||
|
||
for _, m := range matches {
|
||
if !existing[m.rg.MBID] {
|
||
injected = append(injected, m.rg)
|
||
existing[m.rg.MBID] = true
|
||
}
|
||
}
|
||
|
||
if len(injected) > 0 {
|
||
result.ReleaseGroups = append(injected, result.ReleaseGroups...)
|
||
|
||
e.logger.Info("cross-reference injected albums",
|
||
"count", len(injected),
|
||
"topMatch", injected[0].Title,
|
||
)
|
||
}
|
||
}
|
||
|
||
// fuzzyMatchRatio computes a similarity score between query and
|
||
// title. It checks:
|
||
// 1. Whether the title appears as a substring of the query (or
|
||
// vice versa) — handles "for you tatsuro" containing "for you"
|
||
// 2. Word overlap ratio as a fallback
|
||
//
|
||
// Returns 0–1 where 1 is a perfect match.
|
||
func fuzzyMatchRatio(query, title string) float64 {
|
||
if query == title {
|
||
return 1.0
|
||
}
|
||
|
||
// Substring containment: "for you tatsuro" contains "for you".
|
||
// Use both character ratio and word ratio, take the higher one.
|
||
if strings.Contains(query, title) || strings.Contains(title, query) {
|
||
shorter := len(title)
|
||
longer := len(query)
|
||
|
||
if shorter > longer {
|
||
shorter, longer = longer, shorter
|
||
}
|
||
|
||
charRatio := float64(shorter) / float64(longer)
|
||
|
||
// Also check word-level ratio for short titles in long queries.
|
||
titleWords := strings.Fields(title)
|
||
queryWords := strings.Fields(query)
|
||
|
||
wordRatio := float64(len(titleWords)) / float64(len(queryWords))
|
||
if len(titleWords) > len(queryWords) {
|
||
wordRatio = float64(len(queryWords)) / float64(len(titleWords))
|
||
}
|
||
|
||
if wordRatio > charRatio {
|
||
return wordRatio
|
||
}
|
||
|
||
return charRatio
|
||
}
|
||
|
||
// Word overlap: count how many query words appear in the title.
|
||
queryWords := strings.Fields(query)
|
||
titleWords := strings.Fields(title)
|
||
|
||
if len(queryWords) == 0 || len(titleWords) == 0 {
|
||
return 0
|
||
}
|
||
|
||
titleSet := make(map[string]bool, len(titleWords))
|
||
for _, w := range titleWords {
|
||
titleSet[w] = true
|
||
}
|
||
|
||
hits := 0
|
||
|
||
for _, w := range queryWords {
|
||
if titleSet[w] {
|
||
hits++
|
||
}
|
||
}
|
||
|
||
return float64(hits) / float64(len(queryWords))
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Index result merging
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// mergeIndexHits injects local popularity index results into the
|
||
// MBSearchResult. Index hits for entity types not already present
|
||
// (by MBID) are prepended so they appear first — they come from
|
||
// the most popular albums/tracks globally and deserve prominence.
|
||
func mergeIndexHits(result *MBSearchResult, hits []SearchIndexResult) {
|
||
if len(hits) == 0 {
|
||
return
|
||
}
|
||
|
||
// Build MBID sets for existing results.
|
||
artistMBIDs := make(map[string]bool, len(result.Artists))
|
||
for _, a := range result.Artists {
|
||
artistMBIDs[a.MBID] = true
|
||
}
|
||
|
||
rgMBIDs := make(map[string]bool, len(result.ReleaseGroups))
|
||
for _, rg := range result.ReleaseGroups {
|
||
rgMBIDs[rg.MBID] = true
|
||
}
|
||
|
||
recMBIDs := make(map[string]bool, len(result.Recordings))
|
||
for _, r := range result.Recordings {
|
||
recMBIDs[r.MBID] = true
|
||
}
|
||
|
||
// Collect new entries from index that MB didn't return.
|
||
var newArtists []MBArtist
|
||
var newRGs []MBReleaseGroup
|
||
var newRecs []MBRecording
|
||
|
||
for _, h := range hits {
|
||
switch h.EntityType {
|
||
case "artist":
|
||
if !artistMBIDs[h.MBID] {
|
||
score := int(float64(scalePopularity(h.Popularity)) * 0.5)
|
||
|
||
newArtists = append(newArtists, MBArtist{
|
||
MBID: h.MBID,
|
||
Name: h.Title,
|
||
Type: h.ArtistType,
|
||
Country: h.Country,
|
||
Disambiguation: h.Disambiguation,
|
||
SortName: h.SortName,
|
||
Score: score,
|
||
HasPopularity: h.Popularity > 0,
|
||
Popularity: h.Popularity,
|
||
ListenerCount: h.ListenerCount,
|
||
InLibrary: h.InLibrary || h.LocalArtistID > 0,
|
||
LocalID: h.LocalArtistID,
|
||
})
|
||
|
||
artistMBIDs[h.MBID] = true
|
||
}
|
||
|
||
case "release_group":
|
||
if !rgMBIDs[h.MBID] {
|
||
score := int(float64(scalePopularity(h.Popularity)) * 0.5)
|
||
|
||
var secondary []string
|
||
if h.SecondaryTypes != "" {
|
||
secondary = strings.Split(h.SecondaryTypes, ",")
|
||
}
|
||
|
||
newRGs = append(newRGs, MBReleaseGroup{
|
||
MBID: h.MBID,
|
||
Title: h.Title,
|
||
ArtistCredit: h.ArtistName,
|
||
Score: score,
|
||
Popularity: h.Popularity,
|
||
ListenerCount: h.ListenerCount,
|
||
PrimaryType: h.PrimaryType,
|
||
SecondaryTypes: secondary,
|
||
FirstReleaseDate: h.ReleaseDate,
|
||
InLibrary: h.InLibrary || h.LocalReleaseGroupID > 0,
|
||
LocalID: h.LocalReleaseGroupID,
|
||
})
|
||
rgMBIDs[h.MBID] = true
|
||
}
|
||
|
||
case "recording":
|
||
if !recMBIDs[h.MBID] {
|
||
score := int(float64(scalePopularity(h.Popularity)) * 0.5)
|
||
|
||
newRecs = append(newRecs, MBRecording{
|
||
MBID: h.MBID,
|
||
Title: h.Title,
|
||
Length: h.Duration,
|
||
ArtistCredit: h.ArtistName,
|
||
Score: score,
|
||
Popularity: h.Popularity,
|
||
ListenerCount: h.ListenerCount,
|
||
InLibrary: h.InLibrary || h.LocalRecordingID > 0,
|
||
LocalID: h.LocalRecordingID,
|
||
})
|
||
|
||
recMBIDs[h.MBID] = true
|
||
}
|
||
}
|
||
}
|
||
|
||
// Prepend index hits so they appear before MB-only results.
|
||
// The subsequent reranking and filtering passes will sort
|
||
// everything by blended score.
|
||
if len(newArtists) > 0 {
|
||
result.Artists = append(newArtists, result.Artists...)
|
||
}
|
||
|
||
if len(newRGs) > 0 {
|
||
result.ReleaseGroups = append(newRGs, result.ReleaseGroups...)
|
||
}
|
||
|
||
if len(newRecs) > 0 {
|
||
result.Recordings = append(newRecs, result.Recordings...)
|
||
}
|
||
}
|
||
|
||
// scalePopularity maps a raw LB listen count to a 0–100 score
|
||
// comparable with MB/blended scores. Uses log scaling.
|
||
func scalePopularity(listens int) int {
|
||
if listens <= 0 {
|
||
return 0
|
||
}
|
||
|
||
// log10(1M) ≈ 6, log10(10M) ≈ 7. Scale so 1M+ listens → ~80-100.
|
||
const scale = 15.0 // tuned so ~100K listens → ~75, ~1M → ~90
|
||
|
||
score := int(math.Log10(float64(listens)) * scale)
|
||
if score > 100 { //nolint:mnd
|
||
score = 100
|
||
}
|
||
|
||
return score
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Filtering and capping
|
||
// ---------------------------------------------------------------------------
|
||
|
||
func filterAndCap(result *MBSearchResult) {
|
||
// Filter artists: remove SPAs, low-scoring results, and
|
||
// low-popularity garbage when better alternatives exist.
|
||
if len(result.Artists) > 0 {
|
||
filtered := result.Artists[:0]
|
||
|
||
// Find the max popularity among artists to calibrate the
|
||
// garbage threshold. If ANY artist has real popularity,
|
||
// suppress zero-popularity results.
|
||
maxPop := 0
|
||
for _, a := range result.Artists {
|
||
if a.Popularity > maxPop {
|
||
maxPop = a.Popularity
|
||
}
|
||
}
|
||
|
||
for _, a := range result.Artists {
|
||
if mbSpecialPurposeArtists[a.MBID] {
|
||
continue
|
||
}
|
||
|
||
if a.Score < minBlendedScore {
|
||
continue
|
||
}
|
||
|
||
// Drop very-low-popularity results when the result
|
||
// set contains meaningfully popular alternatives.
|
||
if maxPop >= minPopularityFloor && a.HasPopularity && a.Popularity < minPopularityFloor {
|
||
continue
|
||
}
|
||
|
||
filtered = append(filtered, a)
|
||
}
|
||
|
||
result.Artists = filtered
|
||
}
|
||
|
||
// Filter release groups by minimum blended score + popularity floor.
|
||
if len(result.ReleaseGroups) > 0 {
|
||
filtered := result.ReleaseGroups[:0]
|
||
|
||
for _, r := range result.ReleaseGroups {
|
||
if r.Score >= minBlendedScore {
|
||
filtered = append(filtered, r)
|
||
}
|
||
}
|
||
|
||
result.ReleaseGroups = filtered
|
||
}
|
||
|
||
// Filter recordings by minimum blended score.
|
||
if len(result.Recordings) > 0 {
|
||
filtered := result.Recordings[:0]
|
||
|
||
for _, r := range result.Recordings {
|
||
if r.Score >= minBlendedScore {
|
||
filtered = append(filtered, r)
|
||
}
|
||
}
|
||
|
||
result.Recordings = filtered
|
||
}
|
||
|
||
// Cap each slice.
|
||
if len(result.Artists) > maxResults {
|
||
result.Artists = result.Artists[:maxResults]
|
||
}
|
||
|
||
if len(result.ReleaseGroups) > maxResults {
|
||
result.ReleaseGroups = result.ReleaseGroups[:maxResults]
|
||
}
|
||
|
||
if len(result.Recordings) > maxResults {
|
||
result.Recordings = result.Recordings[:maxResults]
|
||
}
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Popularity-boosted reranking
|
||
// ---------------------------------------------------------------------------
|
||
|
||
const (
|
||
// mbSearchLimit is the initial limit passed to each MB search call.
|
||
// The pipeline may re-fetch with a larger limit (up to mbSearchMaxLimit)
|
||
// when MB reports many total matches.
|
||
mbSearchLimit = 25
|
||
|
||
// mbSearchMaxLimit caps the expanded fetch. MB's API maximum is 100.
|
||
mbSearchMaxLimit = 75
|
||
|
||
// indexSearchLimit is the number of results to fetch from the local
|
||
// popularity index (Phase 0). Larger than maxResults because
|
||
// results are filtered and the index is the primary search domain.
|
||
indexSearchLimit = 60
|
||
|
||
// searchMBTimeout is the maximum time to wait for MusicBrainz
|
||
// API responses during interactive search. If MB is slow,
|
||
// results degrade to index-only rather than blocking the user.
|
||
searchMBTimeout = 3 * time.Second
|
||
|
||
// searchSlowPathTimeout caps the total time spent on the slow
|
||
// path (LB popularity + cross-referencing). When the index
|
||
// isn't ready, these API calls can stack up — especially
|
||
// cross-referencing, which browses 3 artist discographies via
|
||
// MB and can hit 429 retries. The timeout ensures search
|
||
// returns within a reasonable window.
|
||
searchSlowPathTimeout = 3 * time.Second
|
||
|
||
// maxResults caps each entity slice after filtering.
|
||
maxResults = 15
|
||
|
||
// minBlendedScore is the absolute floor — no result survives
|
||
// below this regardless of popularity.
|
||
minBlendedScore = 15
|
||
|
||
// minPopularityFloor is the minimum popularity required when
|
||
// higher-popularity alternatives exist. Results below this
|
||
// threshold are dropped unless every result in that entity type
|
||
// is below it (to avoid empty results for niche queries).
|
||
minPopularityFloor = 50
|
||
|
||
relevanceWeight = 0.35
|
||
popularityWeight = 0.50
|
||
personalizationWeight = 0.15
|
||
|
||
// Personalization signal values (0.0–1.0).
|
||
personalInLibrary = 1.0
|
||
personalSimilar = 0.5
|
||
)
|
||
|
||
// tierBonus maps artist name-match tiers to percentage score multipliers.
|
||
// Applied as: score = score * (1 + multiplier). The spread is aggressive:
|
||
// close matches get amplified so popularity can dominate among them,
|
||
// while distant matches get heavily penalized to suppress garbage.
|
||
//
|
||
//nolint:gochecknoglobals
|
||
var tierBonus = map[int]float64{
|
||
0: 0.25, // exact match: +25%
|
||
1: 0.15, // starts with: +15%
|
||
2: -0.10, // substring (query buried in name): -10%
|
||
3: -0.30, // no substring match: -30%
|
||
}
|
||
|
||
// rgTierBonus maps release group match tiers to percentage multipliers.
|
||
// More aggressive spread to suppress results that match neither title
|
||
// nor artist credit.
|
||
//
|
||
//nolint:gochecknoglobals
|
||
var rgTierBonus = map[int]float64{
|
||
0: 0.20, // artist credit exact match: +20%
|
||
1: 0.12, // artist credit contains query: +12%
|
||
2: 0.05, // title exact match: +5%
|
||
3: 0.0, // title contains query: no change
|
||
4: -0.25, // no match: -25%
|
||
}
|
||
|
||
// mbSpecialPurposeArtists is a set of MusicBrainz Special Purpose
|
||
// Artist MBIDs that should be excluded from search results. These
|
||
// are placeholder entries (e.g. [unknown], [anonymous]) that
|
||
// accumulate thousands of recordings and artificially high
|
||
// popularity, polluting search results.
|
||
//
|
||
// See: https://musicbrainz.org/doc/Style/Unknown_and_untitled/Special_purpose_artist
|
||
//
|
||
//nolint:gochecknoglobals
|
||
var mbSpecialPurposeArtists = map[string]bool{
|
||
"125ec42a-7229-4250-afc5-e057484327fe": true, // [unknown]
|
||
"f731ccc4-e22a-43af-a747-64213f8768e7": true, // [anonymous]
|
||
"33cf029c-63b0-41a0-9855-be2a3665fb3b": true, // [data]
|
||
"314e1c25-dde7-4e4d-b2f4-0a7b9f7c56dc": true, // [dialogue]
|
||
"eec63d3c-3b81-4ad4-b1e4-7c147c4d2b61": true, // [no artist]
|
||
"9be7f096-97ec-4615-8957-8c3b659f51b4": true, // [traditional]
|
||
"80a8851f-444c-4539-892b-ad2a49f7f0d0": true, // [Church bells]
|
||
"ae636985-40e8-4fe2-80cb-9c1a21c6e30a": true, // Various Artists (SPA, accumulates bogus popularity)
|
||
"89ad4ac3-39f7-470e-963a-56509c546377": true, // Various Artists (regular MBID, same issue)
|
||
}
|
||
|
||
// boostWithIndexPopularity reranks MB search results using
|
||
// popularity data from the local search index. No API calls —
|
||
// just SQLite lookups. This is the fast path used when the index
|
||
// is ready.
|
||
func (e *Service) boostWithIndexPopularity(result *MBSearchResult) {
|
||
// Collect all MBIDs across all entity types.
|
||
allMBIDs := make([]string, 0,
|
||
len(result.Artists)+len(result.ReleaseGroups)+len(result.Recordings))
|
||
|
||
for _, a := range result.Artists {
|
||
if a.MBID != "" {
|
||
allMBIDs = append(allMBIDs, a.MBID)
|
||
}
|
||
}
|
||
|
||
for _, rg := range result.ReleaseGroups {
|
||
if rg.MBID != "" {
|
||
allMBIDs = append(allMBIDs, rg.MBID)
|
||
}
|
||
}
|
||
|
||
for _, r := range result.Recordings {
|
||
if r.MBID != "" {
|
||
allMBIDs = append(allMBIDs, r.MBID)
|
||
}
|
||
}
|
||
|
||
// Single batch query for all popularity + in_library data.
|
||
batch := e.index.GetPopularityBatch(allMBIDs)
|
||
if batch == nil {
|
||
return
|
||
}
|
||
|
||
// Build per-entity maps from the batch result.
|
||
artistPop := make(map[string]int, len(result.Artists))
|
||
for i, a := range result.Artists {
|
||
if pop, ok := batch.Popularity[a.MBID]; ok {
|
||
artistPop[a.MBID] = pop
|
||
result.Artists[i].HasPopularity = true
|
||
result.Artists[i].Popularity = pop
|
||
}
|
||
|
||
if batch.InLibrary[a.MBID] {
|
||
result.Artists[i].InLibrary = true
|
||
}
|
||
}
|
||
|
||
rerankArtistsPersonalized(result.Artists, artistPop, batch.InLibrary, batch.SimilarityScores)
|
||
|
||
rgPop := make(map[string]int, len(result.ReleaseGroups))
|
||
for i, rg := range result.ReleaseGroups {
|
||
if pop, ok := batch.Popularity[rg.MBID]; ok {
|
||
rgPop[rg.MBID] = pop
|
||
result.ReleaseGroups[i].Popularity = pop
|
||
}
|
||
|
||
if batch.InLibrary[rg.MBID] {
|
||
result.ReleaseGroups[i].InLibrary = true
|
||
}
|
||
}
|
||
|
||
rerankReleaseGroupsPersonalized(result.ReleaseGroups, rgPop, batch.InLibrary, batch.SimilarityScores)
|
||
|
||
recPop := make(map[string]int, len(result.Recordings))
|
||
for i, r := range result.Recordings {
|
||
if pop, ok := batch.Popularity[r.MBID]; ok {
|
||
recPop[r.MBID] = pop
|
||
result.Recordings[i].Popularity = pop
|
||
}
|
||
|
||
if batch.InLibrary[r.MBID] {
|
||
result.Recordings[i].InLibrary = true
|
||
}
|
||
}
|
||
|
||
rerankRecordingsPersonalized(result.Recordings, recPop, batch.InLibrary, batch.SimilarityScores)
|
||
}
|
||
|
||
// boostWithIndexPopularityRGsAndRecs reranks release groups and
|
||
// recordings using index popularity. Artists are handled separately
|
||
// via the always-on LB API lookup.
|
||
func (e *Service) boostWithIndexPopularityRGsAndRecs(result *MBSearchResult) {
|
||
allMBIDs := make([]string, 0,
|
||
len(result.ReleaseGroups)+len(result.Recordings))
|
||
|
||
for _, rg := range result.ReleaseGroups {
|
||
if rg.MBID != "" {
|
||
allMBIDs = append(allMBIDs, rg.MBID)
|
||
}
|
||
}
|
||
|
||
for _, r := range result.Recordings {
|
||
if r.MBID != "" {
|
||
allMBIDs = append(allMBIDs, r.MBID)
|
||
}
|
||
}
|
||
|
||
if len(allMBIDs) == 0 {
|
||
return
|
||
}
|
||
|
||
batch := e.index.GetPopularityBatch(allMBIDs)
|
||
if batch == nil {
|
||
batch = &PopularityBatchResult{
|
||
Popularity: map[string]int{},
|
||
InLibrary: map[string]bool{},
|
||
}
|
||
}
|
||
|
||
// Collect MBIDs the index had no popularity for. For result sets
|
||
// where every candidate has identical MB relevance (e.g. many
|
||
// covers of the same song), missing popularity means the rerank
|
||
// has no signal to pick between them — so fall back to the LB
|
||
// popularity API for just the missing entries. This keeps the
|
||
// common path cache-only while correctness-critical cases get
|
||
// a ~1 round-trip to LB.
|
||
missingRecs := make([]string, 0)
|
||
for _, r := range result.Recordings {
|
||
if r.MBID == "" {
|
||
continue
|
||
}
|
||
if _, ok := batch.Popularity[r.MBID]; !ok {
|
||
missingRecs = append(missingRecs, r.MBID)
|
||
}
|
||
}
|
||
|
||
missingRGs := make([]string, 0)
|
||
for _, rg := range result.ReleaseGroups {
|
||
if rg.MBID == "" {
|
||
continue
|
||
}
|
||
if _, ok := batch.Popularity[rg.MBID]; !ok {
|
||
missingRGs = append(missingRGs, rg.MBID)
|
||
}
|
||
}
|
||
|
||
if len(missingRecs) > 0 || len(missingRGs) > 0 {
|
||
e.fillMissingPopularity(batch, missingRecs, missingRGs)
|
||
}
|
||
|
||
rgPop := make(map[string]int, len(result.ReleaseGroups))
|
||
for i, rg := range result.ReleaseGroups {
|
||
if pop, ok := batch.Popularity[rg.MBID]; ok {
|
||
rgPop[rg.MBID] = pop
|
||
result.ReleaseGroups[i].Popularity = pop
|
||
}
|
||
|
||
if batch.InLibrary[rg.MBID] {
|
||
result.ReleaseGroups[i].InLibrary = true
|
||
}
|
||
}
|
||
|
||
rerankReleaseGroups(result.ReleaseGroups, rgPop)
|
||
|
||
recPop := make(map[string]int, len(result.Recordings))
|
||
for i, r := range result.Recordings {
|
||
if pop, ok := batch.Popularity[r.MBID]; ok {
|
||
recPop[r.MBID] = pop
|
||
result.Recordings[i].Popularity = pop
|
||
}
|
||
|
||
if batch.InLibrary[r.MBID] {
|
||
result.Recordings[i].InLibrary = true
|
||
}
|
||
}
|
||
|
||
rerankRecordings(result.Recordings, recPop)
|
||
}
|
||
|
||
// fillMissingPopularity fetches LB popularity for recordings and
|
||
// release groups that weren't in the local index, merging the
|
||
// results back into batch.Popularity. Also backfills the index in
|
||
// the background so subsequent searches hit the cache. Runs the
|
||
// two LB POST calls concurrently and bounds the total wait to
|
||
// searchSlowPathTimeout so a slow LB response can't block search.
|
||
func (e *Service) fillMissingPopularity(
|
||
batch *PopularityBatchResult,
|
||
missingRecs []string,
|
||
missingRGs []string,
|
||
) {
|
||
ctx, cancel := context.WithTimeout(e.ctx, searchSlowPathTimeout)
|
||
defer cancel()
|
||
|
||
var (
|
||
recPop map[string]PopularityData
|
||
rgPop map[string]PopularityData
|
||
wg sync.WaitGroup
|
||
)
|
||
|
||
if len(missingRecs) > 0 {
|
||
wg.Add(1)
|
||
|
||
go func() {
|
||
defer wg.Done()
|
||
|
||
pop, err := e.lb.RecordingPopularity(ctx, missingRecs)
|
||
if err != nil {
|
||
e.logger.Debug("search: fill missing recording popularity failed",
|
||
"count", len(missingRecs), "error", err)
|
||
|
||
return
|
||
}
|
||
|
||
recPop = pop
|
||
}()
|
||
}
|
||
|
||
if len(missingRGs) > 0 {
|
||
wg.Add(1)
|
||
|
||
go func() {
|
||
defer wg.Done()
|
||
|
||
pop, err := e.lb.ReleaseGroupPopularity(ctx, missingRGs)
|
||
if err != nil {
|
||
e.logger.Debug("search: fill missing RG popularity failed",
|
||
"count", len(missingRGs), "error", err)
|
||
|
||
return
|
||
}
|
||
|
||
rgPop = pop
|
||
}()
|
||
}
|
||
|
||
wg.Wait()
|
||
|
||
// Merge LB results into the batch map so the subsequent rerank
|
||
// picks them up without needing a second lookup path.
|
||
for mbid, data := range recPop {
|
||
batch.Popularity[mbid] = data.ListenCount
|
||
if batch.ListenerCount != nil {
|
||
batch.ListenerCount[mbid] = data.ListenerCount
|
||
}
|
||
}
|
||
|
||
for mbid, data := range rgPop {
|
||
batch.Popularity[mbid] = data.ListenCount
|
||
if batch.ListenerCount != nil {
|
||
batch.ListenerCount[mbid] = data.ListenerCount
|
||
}
|
||
}
|
||
|
||
// Backfill the index in the background so next time this query
|
||
// runs, the index has the answer and we skip the LB round-trip.
|
||
if len(recPop) > 0 {
|
||
go e.index.BackfillPopularity(recPop)
|
||
}
|
||
|
||
if len(rgPop) > 0 {
|
||
go e.index.BackfillPopularity(rgPop)
|
||
}
|
||
}
|
||
|
||
// boostWithPopularityRGsAndRecs fetches LB popularity for release
|
||
// groups and recordings only (artist popularity is fetched separately
|
||
// in the main search path). Runs two concurrent POST calls.
|
||
func (e *Service) boostWithPopularityRGsAndRecs(result *MBSearchResult) {
|
||
recordingMBIDs := make([]string, len(result.Recordings))
|
||
for i, r := range result.Recordings {
|
||
recordingMBIDs[i] = r.MBID
|
||
}
|
||
|
||
rgMBIDs := make([]string, len(result.ReleaseGroups))
|
||
for i, rg := range result.ReleaseGroups {
|
||
rgMBIDs[i] = rg.MBID
|
||
}
|
||
|
||
// Fetch popularity concurrently (2 POST calls).
|
||
var (
|
||
recordingPopData map[string]PopularityData
|
||
rgPopData map[string]PopularityData
|
||
wg sync.WaitGroup
|
||
)
|
||
|
||
wg.Add(2) //nolint:mnd
|
||
|
||
go func() {
|
||
defer wg.Done()
|
||
|
||
pop, err := e.lb.RecordingPopularity(e.ctx, recordingMBIDs)
|
||
if err != nil {
|
||
e.logger.Warn("popularity lookup failed", "entity", "recording", "error", err)
|
||
|
||
return
|
||
}
|
||
|
||
recordingPopData = pop
|
||
}()
|
||
|
||
go func() {
|
||
defer wg.Done()
|
||
|
||
pop, err := e.lb.ReleaseGroupPopularity(e.ctx, rgMBIDs)
|
||
if err != nil {
|
||
e.logger.Warn("popularity lookup failed", "entity", "releaseGroup", "error", err)
|
||
|
||
return
|
||
}
|
||
|
||
rgPopData = pop
|
||
}()
|
||
|
||
wg.Wait()
|
||
|
||
// Backfill index with popularity data for future searches.
|
||
if recordingPopData != nil {
|
||
go e.index.BackfillPopularity(recordingPopData)
|
||
}
|
||
|
||
if rgPopData != nil {
|
||
go e.index.BackfillPopularity(rgPopData)
|
||
}
|
||
|
||
rerankRecordings(result.Recordings, listenCounts(recordingPopData))
|
||
rerankReleaseGroups(result.ReleaseGroups, listenCounts(rgPopData))
|
||
}
|
||
|
||
// boostNameMatches re-sorts artists and release groups so that
|
||
// exact or substring name matches rank above results that only
|
||
// matched on common words like "the". Without this, a search
|
||
// for "the teenagers" would rank The Beatles above The Teenagers
|
||
// because The Beatles' massive popularity compensates for their
|
||
// weak text relevance on the word "the".
|
||
//
|
||
// The boost is applied after popularity reranking so it acts as
|
||
// a final tiebreaker that respects user intent.
|
||
func (e *Service) boostNameMatches(query string, result *MBSearchResult) {
|
||
q := strings.ToLower(strings.TrimSpace(query))
|
||
if q == "" {
|
||
return
|
||
}
|
||
|
||
// Apply tier multiplier to artist scores. Percentage-based so the
|
||
// boost scales with the artist's existing score — a popular
|
||
// near-match can overcome an unpopular exact match when the
|
||
// popularity gap is proportionally larger than the tier difference.
|
||
if len(result.Artists) > 1 {
|
||
for i := range result.Artists {
|
||
tier := nameMatchTier(q, strings.ToLower(result.Artists[i].Name))
|
||
result.Artists[i].Score = int(float64(result.Artists[i].Score) * (1.0 + tierBonus[tier]))
|
||
}
|
||
|
||
sort.SliceStable(result.Artists, func(i, j int) bool {
|
||
return result.Artists[i].Score > result.Artists[j].Score
|
||
})
|
||
|
||
// For same-named artists in tier 0, resolve ordering via
|
||
// a targeted LB popularity lookup.
|
||
e.disambiguateSameNameArtists(q, result.Artists)
|
||
}
|
||
|
||
// Apply tier multiplier to release group scores.
|
||
if len(result.ReleaseGroups) > 1 {
|
||
for i := range result.ReleaseGroups {
|
||
tier := rgMatchTier(q,
|
||
strings.ToLower(result.ReleaseGroups[i].Title),
|
||
strings.ToLower(result.ReleaseGroups[i].ArtistCredit))
|
||
result.ReleaseGroups[i].Score = int(float64(result.ReleaseGroups[i].Score) * (1.0 + rgTierBonus[tier]))
|
||
}
|
||
|
||
sort.SliceStable(result.ReleaseGroups, func(i, j int) bool {
|
||
return result.ReleaseGroups[i].Score > result.ReleaseGroups[j].Score
|
||
})
|
||
}
|
||
}
|
||
|
||
// disambiguateSameNameArtists resolves ordering among artists
|
||
// that share the exact same name as the query by fetching their
|
||
// LB popularity. This is a targeted micro-lookup (typically 2-6
|
||
// MBIDs) that only fires when the index fast path couldn't
|
||
// meaningfully differentiate same-named artists.
|
||
func (e *Service) disambiguateSameNameArtists(query string, artists []MBArtist) {
|
||
// Find the contiguous block of tier-0 same-name artists at the front.
|
||
var sameNameEnd int
|
||
|
||
for sameNameEnd < len(artists) {
|
||
if strings.ToLower(artists[sameNameEnd].Name) != query {
|
||
break
|
||
}
|
||
|
||
sameNameEnd++
|
||
}
|
||
|
||
if sameNameEnd < 2 {
|
||
return // 0 or 1 same-name artists — nothing to disambiguate
|
||
}
|
||
|
||
// Collect MBIDs for the targeted LB lookup.
|
||
mbids := make([]string, 0, sameNameEnd)
|
||
for i := range sameNameEnd {
|
||
if artists[i].MBID != "" {
|
||
mbids = append(mbids, artists[i].MBID)
|
||
}
|
||
}
|
||
|
||
if len(mbids) < 2 {
|
||
return
|
||
}
|
||
|
||
pop, err := e.lb.ArtistPopularity(e.ctx, mbids)
|
||
if err != nil || len(pop) == 0 {
|
||
return
|
||
}
|
||
|
||
// Re-sort the same-name block by LB popularity descending.
|
||
sort.SliceStable(artists[:sameNameEnd], func(i, j int) bool {
|
||
return pop[artists[i].MBID].ListenCount > pop[artists[j].MBID].ListenCount
|
||
})
|
||
}
|
||
|
||
// nameMatchTier returns a tier value for how well a name matches
|
||
// the query. Lower is better:
|
||
//
|
||
// 0 = exact match ("the teenagers" == "the teenagers")
|
||
// 1 = name starts with query ("the teenagers" in "the teenagers feat. X")
|
||
// 2 = query is a substring ("the teenagers" in "al supersonic & the teenagers")
|
||
// 3 = no substring match (only individual words matched)
|
||
func nameMatchTier(query, name string) int {
|
||
if name == query {
|
||
return 0
|
||
}
|
||
|
||
if strings.HasPrefix(name, query) {
|
||
return 1
|
||
}
|
||
|
||
if strings.Contains(name, query) {
|
||
return 2
|
||
}
|
||
|
||
return 3
|
||
}
|
||
|
||
// rgMatchTier returns a tier for release groups considering both
|
||
// the title and artist credit. An album by "Hop Along" called
|
||
// "Painted Shut" should rank above a tribute album called
|
||
// "A Hop Along Tribute" by Various Artists.
|
||
//
|
||
// 0 = artist credit matches query exactly ("hop along" == "hop along")
|
||
// 1 = artist credit starts with or contains query
|
||
// 2 = title matches query exactly
|
||
// 3 = title starts with or contains query
|
||
// 4 = no match in either field
|
||
func rgMatchTier(query, title, artistCredit string) int {
|
||
// Artist credit match is stronger — it means the album is BY
|
||
// the searched artist, not just mentioning them in the title.
|
||
if artistCredit == query {
|
||
return 0
|
||
}
|
||
|
||
if strings.Contains(artistCredit, query) {
|
||
return 1
|
||
}
|
||
|
||
// Title match — the album name contains the query.
|
||
if title == query {
|
||
return 2
|
||
}
|
||
|
||
if strings.Contains(title, query) {
|
||
return 3
|
||
}
|
||
|
||
return 4
|
||
}
|
||
|
||
// rerankArtists sorts artists by blended score and updates their
|
||
// Score field to the new value (0–100 scale).
|
||
func rerankArtists(artists []MBArtist, pop map[string]int, libraryMBIDs map[string]bool) {
|
||
rerankArtistsPersonalized(artists, pop, libraryMBIDs, nil)
|
||
}
|
||
|
||
func rerankArtistsPersonalized(artists []MBArtist, pop map[string]int, inLib map[string]bool, simScores map[string]int) {
|
||
if len(artists) == 0 {
|
||
return
|
||
}
|
||
|
||
maxPop := maxListenCount(pop)
|
||
maxSim := maxSimScoreVal(simScores)
|
||
|
||
sort.SliceStable(artists, func(i, j int) bool {
|
||
si := blendedScoreFull(float64(artists[i].Score)/100.0, pop[artists[i].MBID], maxPop, personalScore(artists[i].MBID, inLib, simScores, maxSim))
|
||
sj := blendedScoreFull(float64(artists[j].Score)/100.0, pop[artists[j].MBID], maxPop, personalScore(artists[j].MBID, inLib, simScores, maxSim))
|
||
return si > sj
|
||
})
|
||
|
||
for i := range artists {
|
||
s := blendedScoreFull(float64(artists[i].Score)/100.0, pop[artists[i].MBID], maxPop, personalScore(artists[i].MBID, inLib, simScores, maxSim))
|
||
artists[i].Score = int(s * 100)
|
||
}
|
||
}
|
||
|
||
// rerankRecordings sorts recordings by blended score and updates
|
||
// their Score field.
|
||
func rerankRecordings(recordings []MBRecording, pop map[string]int) {
|
||
rerankRecordingsPersonalized(recordings, pop, nil, nil)
|
||
}
|
||
|
||
func rerankRecordingsPersonalized(recordings []MBRecording, pop map[string]int, inLib map[string]bool, simScores map[string]int) {
|
||
if len(recordings) == 0 {
|
||
return
|
||
}
|
||
|
||
maxPop := maxListenCount(pop)
|
||
maxSim := maxSimScoreVal(simScores)
|
||
|
||
sort.SliceStable(recordings, func(i, j int) bool {
|
||
si := blendedScoreFull(float64(recordings[i].Score)/100.0, pop[recordings[i].MBID], maxPop, personalScore(recordings[i].MBID, inLib, simScores, maxSim))
|
||
sj := blendedScoreFull(float64(recordings[j].Score)/100.0, pop[recordings[j].MBID], maxPop, personalScore(recordings[j].MBID, inLib, simScores, maxSim))
|
||
return si > sj
|
||
})
|
||
|
||
for i := range recordings {
|
||
s := blendedScoreFull(float64(recordings[i].Score)/100.0, pop[recordings[i].MBID], maxPop, personalScore(recordings[i].MBID, inLib, simScores, maxSim))
|
||
recordings[i].Score = int(s * 100)
|
||
}
|
||
}
|
||
|
||
// rerankReleaseGroups sorts release groups by blended score
|
||
// (text relevance + popularity + personalization) and updates their Score field.
|
||
func rerankReleaseGroups(rgs []MBReleaseGroup, pop map[string]int) {
|
||
rerankReleaseGroupsPersonalized(rgs, pop, nil, nil)
|
||
}
|
||
|
||
func rerankReleaseGroupsPersonalized(rgs []MBReleaseGroup, pop map[string]int, inLib map[string]bool, simScores map[string]int) {
|
||
if len(rgs) == 0 {
|
||
return
|
||
}
|
||
|
||
maxPop := maxListenCount(pop)
|
||
maxSim := maxSimScoreVal(simScores)
|
||
|
||
sort.SliceStable(rgs, func(i, j int) bool {
|
||
si := blendedScoreFull(float64(rgs[i].Score)/100.0, pop[rgs[i].MBID], maxPop, personalScore(rgs[i].MBID, inLib, simScores, maxSim))
|
||
sj := blendedScoreFull(float64(rgs[j].Score)/100.0, pop[rgs[j].MBID], maxPop, personalScore(rgs[j].MBID, inLib, simScores, maxSim))
|
||
return si > sj
|
||
})
|
||
|
||
for i := range rgs {
|
||
s := blendedScoreFull(float64(rgs[i].Score)/100.0, pop[rgs[i].MBID], maxPop, personalScore(rgs[i].MBID, inLib, simScores, maxSim))
|
||
rgs[i].Score = int(s * 100)
|
||
}
|
||
}
|
||
|
||
// maxSimScoreVal returns the highest similarity score in the map.
|
||
func maxSimScoreVal(scores map[string]int) int {
|
||
maxVal := 0
|
||
for _, v := range scores {
|
||
if v > maxVal {
|
||
maxVal = v
|
||
}
|
||
}
|
||
|
||
return maxVal
|
||
}
|
||
|
||
// personalScore returns the personalization signal (0.0–1.0) for an MBID.
|
||
// Uses similarity scores from similar_artist_map, scaled by the max score
|
||
// in the batch so the most similar artist gets the full personalSimilar weight.
|
||
func personalScore(mbid string, inLib map[string]bool, simScores map[string]int, maxSimScore int) float64 {
|
||
if inLib[mbid] {
|
||
return personalInLibrary
|
||
}
|
||
|
||
if score, ok := simScores[mbid]; ok && score > 0 && maxSimScore > 0 {
|
||
return personalSimilar * (float64(score) / float64(maxSimScore))
|
||
}
|
||
|
||
return 0.0
|
||
}
|
||
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Top Results — intent-scored cards
|
||
// ---------------------------------------------------------------------------
|
||
|
||
const (
|
||
// topResultsMax is the maximum number of top-result cards to
|
||
// return. Bounded because they occupy expensive horizontal
|
||
// screen real estate above the main search lists.
|
||
topResultsMax = 5
|
||
|
||
// topResultsPerCatMax caps how many cards from a single
|
||
// category can appear in the final selection. Keeps the row
|
||
// from being all-artists or all-recordings on lopsided queries.
|
||
topResultsPerCatMax = 2
|
||
|
||
// topResultsMinScore is the absolute floor for a candidate's
|
||
// final score (quality * prior). Nothing below this survives,
|
||
// regardless of category or rank.
|
||
topResultsMinScore = 0.08
|
||
|
||
// topResultsCandidates is how many candidates per category
|
||
// feed into intent scoring. Larger = more chances to surface
|
||
// a better card, smaller = faster and less susceptible to
|
||
// main-rerank noise.
|
||
topResultsCandidates = 10
|
||
|
||
// topResultsExactScanLimit caps how deep into each main result
|
||
// list we'll scan for exact title/artist matches that didn't
|
||
// make the top-N rerank. This is the safety net for the case
|
||
// where MB returns dozens of identically-relevant candidates
|
||
// (covers of a popular song) and the rerank fails to surface
|
||
// the canonical version because its popularity isn't indexed.
|
||
topResultsExactScanLimit = 50
|
||
|
||
// topResultsExactCap is how many exact-match candidates per
|
||
// category can enter the candidate pool from the dedicated
|
||
// ExactMatches retrieval source.
|
||
topResultsExactCap = 3
|
||
|
||
// topResultsClickDecay is the half-life of a per-query click
|
||
// boost in days. Longer = stickier, shorter = more
|
||
// responsive to recent intent.
|
||
topResultsClickDecay = 30.0
|
||
|
||
// topResultsRowConfidence is the minimum gap between the
|
||
// winning category's intent prior and the runner-up before we
|
||
// show the row at all. Below this we hide the row entirely
|
||
// — it's better to show nothing than a wrong guess.
|
||
topResultsRowConfidence = 0.12
|
||
|
||
// Feature weights for candidate quality scoring. Sum is not
|
||
// required to be 1.0 because the final score is multiplied
|
||
// by the intent prior separately. Tune these against
|
||
// specific query cases that behave wrong.
|
||
fwExactTitle = 1.00 // normalized title matches query exactly
|
||
fwExactArtist = 0.90 // artist name matches query exactly
|
||
fwPrefixTitle = 0.60 // title starts with query
|
||
fwContainsWord = 0.40 // title contains query as a whole word
|
||
fwContainsAny = 0.20 // title has query as any substring
|
||
fwListenLog = 0.80 // log-scaled listen count (0 when 0 listens)
|
||
fwListenerLog = 0.60 // log-scaled listener count
|
||
fwInLibrary = 0.50 // owned by the user
|
||
fwSimilar = 0.20 // similar to an owned artist
|
||
fwClusterBig = 0.15 // release-group is a known canonical (many releases)
|
||
fwOfficialOnly = 0.10 // official-status release only (not a bootleg)
|
||
|
||
// priorAlpha controls how much the intent prior influences
|
||
// final ranking. Higher values make category dominance
|
||
// more decisive; lower values let individual quality scores
|
||
// win across categories.
|
||
priorAlpha = 1.5
|
||
)
|
||
|
||
// resolveTopResults computes intent-scored top result cards from the
|
||
// already-reranked search results plus a dedicated exact-match
|
||
// retrieval source. Returns 0-5 cards sorted by final score
|
||
// descending.
|
||
//
|
||
// Pipeline:
|
||
// 1. Retrieve candidates from three sources: top-N per category from
|
||
// the main reranked result + exact title/artist matches from the
|
||
// local index. Union them, deduping by MBID.
|
||
// 2. Score each candidate using a featurized additive scorer with
|
||
// explicit named features. Quality is purely candidate-side; no
|
||
// cross-candidate normalization.
|
||
// 3. Compute a category intent prior from the catalog signals
|
||
// (listen-count distribution per category, query shape rules,
|
||
// exact-match counts). Multiply quality by prior^alpha.
|
||
// 4. Sort by final score, apply per-category caps and the row-level
|
||
// confidence threshold. Return up to topResultsMax cards.
|
||
func (e *Service) resolveTopResults(query string, result *MBSearchResult) []TopResult {
|
||
q := strings.ToLower(strings.TrimSpace(query))
|
||
if q == "" {
|
||
return nil
|
||
}
|
||
|
||
// Stage 1: gather candidates.
|
||
clicks := e.getSearchClicks(q)
|
||
exactMatches := e.index.ExactMatches(q, topResultsExactCap)
|
||
candidates := e.gatherTopCandidates(q, result, exactMatches, clicks)
|
||
if len(candidates) == 0 {
|
||
return nil
|
||
}
|
||
|
||
// Identify candidates that hit an exact-match feature so the
|
||
// intent prior can boost their categories accordingly. This
|
||
// is what catches Blue October's "Calling You" — even if the
|
||
// local index never heard of Blue October, the MB result list
|
||
// has the recording with title == query, and the prior should
|
||
// know that strengthens the recording category. Composite
|
||
// matches (query contains both the title and the artist of a
|
||
// recording or album) are treated the same way.
|
||
var exactCandidates []topCandidate
|
||
for _, c := range candidates {
|
||
isExact := isExactNameMatch(q, c.topResult.Name) ||
|
||
isExactNameMatch(q, c.topResult.ArtistCredit) ||
|
||
isCompositeMatch(q, c.topResult.Name, c.topResult.ArtistCredit)
|
||
if isExact {
|
||
exactCandidates = append(exactCandidates, c)
|
||
}
|
||
}
|
||
|
||
// Stage 2: compute the category intent prior.
|
||
prior := e.computeIntentPrior(q, result, exactMatches, exactCandidates)
|
||
|
||
// Confidence gate: hide the row entirely if no category clearly
|
||
// dominates. Better to show nothing than a wrong guess.
|
||
//
|
||
// Override: if any candidate hits an exact match against an
|
||
// entity with non-zero listener count, the row should always
|
||
// show. An exact match is itself a confidence signal — even
|
||
// when shape and listener-distribution don't agree.
|
||
confident := priorConfidence(prior) >= topResultsRowConfidence
|
||
if !confident {
|
||
for _, c := range exactCandidates {
|
||
if c.qualityScore >= 1.0 { // exact match contributes >= fwExactTitle
|
||
confident = true
|
||
|
||
break
|
||
}
|
||
}
|
||
}
|
||
|
||
if !confident {
|
||
e.logger.Info("search top results: prior too flat, hiding row",
|
||
"query", query,
|
||
"candidates", len(candidates),
|
||
"exact_candidates", len(exactCandidates),
|
||
"prior_artist", prior.artist,
|
||
"prior_album", prior.album,
|
||
"prior_recording", prior.recording,
|
||
)
|
||
|
||
return nil
|
||
}
|
||
|
||
// Stage 3: combine quality with prior.
|
||
for i := range candidates {
|
||
c := &candidates[i]
|
||
|
||
var p float64
|
||
|
||
switch c.category {
|
||
case "artist":
|
||
p = prior.artist
|
||
case "release_group":
|
||
p = prior.album
|
||
case "recording":
|
||
p = prior.recording
|
||
}
|
||
|
||
c.finalScore = c.qualityScore * math.Pow(p, priorAlpha)
|
||
}
|
||
|
||
// Stage 4: sort, dedupe by MBID, apply caps.
|
||
sort.SliceStable(candidates, func(i, j int) bool {
|
||
return candidates[i].finalScore > candidates[j].finalScore
|
||
})
|
||
|
||
catCount := make(map[string]int, 3) //nolint:mnd
|
||
seen := make(map[string]bool, len(candidates))
|
||
|
||
var selected []TopResult
|
||
|
||
for _, c := range candidates {
|
||
if len(selected) >= topResultsMax {
|
||
break
|
||
}
|
||
|
||
if c.finalScore < topResultsMinScore {
|
||
break
|
||
}
|
||
|
||
if catCount[c.category] >= topResultsPerCatMax {
|
||
continue
|
||
}
|
||
|
||
if seen[c.topResult.MBID] {
|
||
continue
|
||
}
|
||
|
||
c.topResult.IntentScore = c.finalScore
|
||
selected = append(selected, c.topResult)
|
||
catCount[c.category]++
|
||
seen[c.topResult.MBID] = true
|
||
}
|
||
|
||
if len(selected) > 0 {
|
||
topName := selected[0].Name
|
||
if selected[0].ArtistCredit != "" {
|
||
topName = topName + " — " + selected[0].ArtistCredit
|
||
}
|
||
|
||
e.logger.Info("search top results selected",
|
||
"query", query,
|
||
"count", len(selected),
|
||
"candidates", len(candidates),
|
||
"exact_candidates", len(exactCandidates),
|
||
"prior_artist", prior.artist,
|
||
"prior_album", prior.album,
|
||
"prior_recording", prior.recording,
|
||
"top", topName,
|
||
"top_score", selected[0].IntentScore,
|
||
)
|
||
}
|
||
|
||
return selected
|
||
}
|
||
|
||
// topCandidate is a single scored candidate flowing through the
|
||
// top-results pipeline. qualityScore is the per-candidate signal
|
||
// without category bias; finalScore is qualityScore multiplied by
|
||
// the category prior at selection time.
|
||
type topCandidate struct {
|
||
topResult TopResult
|
||
category string
|
||
qualityScore float64
|
||
finalScore float64
|
||
}
|
||
|
||
// intentPrior is a probability distribution over the three entity
|
||
// categories: how likely the user is searching for an artist, an
|
||
// album, or a recording. Sums to 1.0.
|
||
type intentPrior struct {
|
||
artist float64
|
||
album float64
|
||
recording float64
|
||
}
|
||
|
||
// gatherTopCandidates builds the candidate pool from the top-N
|
||
// per category of the main reranked result plus exact-match results
|
||
// from two sources: the dedicated local-index ExactMatches lookup
|
||
// and any results in the MB list whose title/artist exactly equal
|
||
// the query. Each candidate is scored once with the featurized
|
||
// quality scorer. Duplicates (same MBID) are deduped, keeping the
|
||
// highest quality score.
|
||
func (e *Service) gatherTopCandidates(
|
||
q string,
|
||
result *MBSearchResult,
|
||
exactMatches []SearchIndexResult,
|
||
clicks map[string]searchClick,
|
||
) []topCandidate {
|
||
candidates := make([]topCandidate, 0, topResultsCandidates*3+len(exactMatches))
|
||
byMBID := make(map[string]int, cap(candidates))
|
||
|
||
add := func(cand topCandidate) {
|
||
if cand.topResult.MBID == "" {
|
||
return
|
||
}
|
||
|
||
if existing, ok := byMBID[cand.topResult.MBID]; ok {
|
||
if cand.qualityScore > candidates[existing].qualityScore {
|
||
candidates[existing] = cand
|
||
}
|
||
|
||
return
|
||
}
|
||
|
||
byMBID[cand.topResult.MBID] = len(candidates)
|
||
candidates = append(candidates, cand)
|
||
}
|
||
|
||
// Source 1: top-N artists from the main rerank.
|
||
limit := topResultsCandidates
|
||
if limit > len(result.Artists) {
|
||
limit = len(result.Artists)
|
||
}
|
||
|
||
for i := 0; i < limit; i++ {
|
||
a := result.Artists[i]
|
||
|
||
quality := e.scoreArtistCandidate(q, &a, clicks)
|
||
add(topCandidate{
|
||
topResult: TopResult{
|
||
EntityType: "artist",
|
||
MBID: a.MBID,
|
||
Name: a.Name,
|
||
ArtistType: a.Type,
|
||
Country: a.Country,
|
||
InLibrary: a.InLibrary,
|
||
},
|
||
category: "artist",
|
||
qualityScore: quality,
|
||
})
|
||
}
|
||
|
||
// Source 1b: scan the entire artist list (capped at
|
||
// topResultsExactScanLimit) for exact name matches that didn't
|
||
// make the top-N rerank. Without this, an artist with a
|
||
// perfect name match buried at position 12 by the rerank
|
||
// could never become a top-result candidate.
|
||
scanLimit := topResultsExactScanLimit
|
||
if scanLimit > len(result.Artists) {
|
||
scanLimit = len(result.Artists)
|
||
}
|
||
|
||
for i := topResultsCandidates; i < scanLimit; i++ {
|
||
a := result.Artists[i]
|
||
if !isExactNameMatch(q, a.Name) {
|
||
continue
|
||
}
|
||
|
||
quality := e.scoreArtistCandidate(q, &a, clicks)
|
||
add(topCandidate{
|
||
topResult: TopResult{
|
||
EntityType: "artist",
|
||
MBID: a.MBID,
|
||
Name: a.Name,
|
||
ArtistType: a.Type,
|
||
Country: a.Country,
|
||
InLibrary: a.InLibrary,
|
||
},
|
||
category: "artist",
|
||
qualityScore: quality,
|
||
})
|
||
}
|
||
|
||
// Source 2: top-N release groups from the main rerank.
|
||
limit = topResultsCandidates
|
||
if limit > len(result.ReleaseGroups) {
|
||
limit = len(result.ReleaseGroups)
|
||
}
|
||
|
||
for i := 0; i < limit; i++ {
|
||
rg := result.ReleaseGroups[i]
|
||
|
||
quality := e.scoreReleaseGroupCandidate(q, &rg, clicks)
|
||
year := ""
|
||
if len(rg.FirstReleaseDate) >= 4 { //nolint:mnd
|
||
year = rg.FirstReleaseDate[:4]
|
||
}
|
||
|
||
add(topCandidate{
|
||
topResult: TopResult{
|
||
EntityType: "release_group",
|
||
MBID: rg.MBID,
|
||
Name: rg.Title,
|
||
ArtistCredit: rg.ArtistCredit,
|
||
PrimaryType: rg.PrimaryType,
|
||
Year: year,
|
||
InLibrary: rg.InLibrary,
|
||
},
|
||
category: "release_group",
|
||
qualityScore: quality,
|
||
})
|
||
}
|
||
|
||
// Source 2b: scan the rest of the release-group list for
|
||
// exact title or artist matches. Same rationale as Source 1b.
|
||
// Also catches composite matches (e.g. "abbey road beatles").
|
||
scanLimit = topResultsExactScanLimit
|
||
if scanLimit > len(result.ReleaseGroups) {
|
||
scanLimit = len(result.ReleaseGroups)
|
||
}
|
||
|
||
for i := topResultsCandidates; i < scanLimit; i++ {
|
||
rg := result.ReleaseGroups[i]
|
||
|
||
exactTitle := isExactNameMatch(q, rg.Title)
|
||
exactArtist := isExactNameMatch(q, rg.ArtistCredit)
|
||
composite := isCompositeMatch(q, rg.Title, rg.ArtistCredit)
|
||
|
||
if !exactTitle && !exactArtist && !composite {
|
||
continue
|
||
}
|
||
|
||
quality := e.scoreReleaseGroupCandidate(q, &rg, clicks)
|
||
if composite && !exactTitle && !exactArtist {
|
||
quality += fwExactTitle
|
||
}
|
||
|
||
year := ""
|
||
if len(rg.FirstReleaseDate) >= 4 { //nolint:mnd
|
||
year = rg.FirstReleaseDate[:4]
|
||
}
|
||
|
||
add(topCandidate{
|
||
topResult: TopResult{
|
||
EntityType: "release_group",
|
||
MBID: rg.MBID,
|
||
Name: rg.Title,
|
||
ArtistCredit: rg.ArtistCredit,
|
||
PrimaryType: rg.PrimaryType,
|
||
Year: year,
|
||
InLibrary: rg.InLibrary,
|
||
},
|
||
category: "release_group",
|
||
qualityScore: quality,
|
||
})
|
||
}
|
||
|
||
// Source 3: top-N recordings from the main rerank.
|
||
limit = topResultsCandidates
|
||
if limit > len(result.Recordings) {
|
||
limit = len(result.Recordings)
|
||
}
|
||
|
||
for i := 0; i < limit; i++ {
|
||
r := result.Recordings[i]
|
||
|
||
quality := e.scoreRecordingCandidate(q, &r, clicks)
|
||
add(topCandidate{
|
||
topResult: TopResult{
|
||
EntityType: "recording",
|
||
MBID: r.MBID,
|
||
Name: r.Title,
|
||
ArtistCredit: r.ArtistCredit,
|
||
Length: r.Length,
|
||
InLibrary: r.InLibrary,
|
||
},
|
||
category: "recording",
|
||
qualityScore: quality,
|
||
})
|
||
}
|
||
|
||
// Source 3b: scan the rest of the recording list for exact
|
||
// matches. This is the critical fix for the case where MB
|
||
// returns 75 recordings all with relevance 100 — the rerank
|
||
// can only differentiate them by popularity (which may be
|
||
// missing for many), so a popular exact match like Blue
|
||
// October's "Calling You" might land at position 11+. By
|
||
// scanning the full list for exact matches, we surface them
|
||
// regardless of where the rerank put them.
|
||
//
|
||
// Also catches "composite" matches: when the query contains
|
||
// both the recording title AND the artist credit (e.g.
|
||
// "calling you blue october"), the recording is a strong
|
||
// candidate even though neither field equals the full query.
|
||
scanLimit = topResultsExactScanLimit
|
||
if scanLimit > len(result.Recordings) {
|
||
scanLimit = len(result.Recordings)
|
||
}
|
||
|
||
for i := topResultsCandidates; i < scanLimit; i++ {
|
||
r := result.Recordings[i]
|
||
|
||
exactTitle := isExactNameMatch(q, r.Title)
|
||
exactArtist := isExactNameMatch(q, r.ArtistCredit)
|
||
composite := isCompositeMatch(q, r.Title, r.ArtistCredit)
|
||
|
||
if !exactTitle && !exactArtist && !composite {
|
||
continue
|
||
}
|
||
|
||
quality := e.scoreRecordingCandidate(q, &r, clicks)
|
||
|
||
// Composite matches don't get the exact-title feature
|
||
// from the scorer (because neither field equals the
|
||
// query), so add the bonus explicitly here so they
|
||
// compete with title-only exact matches.
|
||
if composite && !exactTitle && !exactArtist {
|
||
quality += fwExactTitle
|
||
}
|
||
|
||
add(topCandidate{
|
||
topResult: TopResult{
|
||
EntityType: "recording",
|
||
MBID: r.MBID,
|
||
Name: r.Title,
|
||
ArtistCredit: r.ArtistCredit,
|
||
Length: r.Length,
|
||
InLibrary: r.InLibrary,
|
||
},
|
||
category: "recording",
|
||
qualityScore: quality,
|
||
})
|
||
}
|
||
|
||
// Source 4: exact matches from the local index. These bypass
|
||
// the main rerank entirely so a high-popularity entity buried
|
||
// at position 8 in the MB result list still gets surfaced.
|
||
for _, m := range exactMatches {
|
||
quality := e.scoreExactMatch(q, &m, clicks)
|
||
|
||
switch m.EntityType {
|
||
case "artist":
|
||
add(topCandidate{
|
||
topResult: TopResult{
|
||
EntityType: "artist",
|
||
MBID: m.MBID,
|
||
Name: m.Title,
|
||
ArtistType: m.ArtistType,
|
||
Country: m.Country,
|
||
InLibrary: m.InLibrary || m.LocalArtistID > 0,
|
||
},
|
||
category: "artist",
|
||
qualityScore: quality,
|
||
})
|
||
case "release_group":
|
||
year := ""
|
||
if len(m.ReleaseDate) >= 4 { //nolint:mnd
|
||
year = m.ReleaseDate[:4]
|
||
}
|
||
|
||
add(topCandidate{
|
||
topResult: TopResult{
|
||
EntityType: "release_group",
|
||
MBID: m.MBID,
|
||
Name: m.Title,
|
||
ArtistCredit: m.ArtistName,
|
||
PrimaryType: m.PrimaryType,
|
||
Year: year,
|
||
InLibrary: m.InLibrary || m.LocalReleaseGroupID > 0,
|
||
},
|
||
category: "release_group",
|
||
qualityScore: quality,
|
||
})
|
||
case "recording":
|
||
add(topCandidate{
|
||
topResult: TopResult{
|
||
EntityType: "recording",
|
||
MBID: m.MBID,
|
||
Name: m.Title,
|
||
ArtistCredit: m.ArtistName,
|
||
Length: m.Duration,
|
||
InLibrary: m.InLibrary || m.LocalRecordingID > 0,
|
||
},
|
||
category: "recording",
|
||
qualityScore: quality,
|
||
})
|
||
}
|
||
}
|
||
|
||
return candidates
|
||
}
|
||
|
||
// scoreArtistCandidate computes the featurized quality score for an
|
||
// artist top-result candidate. Pure additive — no cross-candidate
|
||
// normalization, no popularity squaring.
|
||
func (e *Service) scoreArtistCandidate(
|
||
q string,
|
||
a *MBArtist,
|
||
clicks map[string]searchClick,
|
||
) float64 {
|
||
name := strings.ToLower(a.Name)
|
||
qn := normalizeForMatch(q)
|
||
nn := normalizeForMatch(a.Name)
|
||
|
||
score := 0.0
|
||
|
||
switch {
|
||
case nn == qn:
|
||
score += fwExactTitle
|
||
case strings.HasPrefix(name, q):
|
||
score += fwPrefixTitle
|
||
case containsWord(name, q):
|
||
score += fwContainsWord
|
||
case strings.Contains(name, q):
|
||
score += fwContainsAny
|
||
}
|
||
|
||
score += fwListenLog * normLog(a.Popularity)
|
||
score += fwListenerLog * normLog(a.ListenerCount)
|
||
|
||
if a.InLibrary {
|
||
score += fwInLibrary
|
||
}
|
||
|
||
if cb := clicks[a.MBID]; cb.count > 0 {
|
||
score += clickFeature(cb)
|
||
}
|
||
|
||
return score
|
||
}
|
||
|
||
// scoreReleaseGroupCandidate computes the featurized quality score
|
||
// for a release-group top-result candidate.
|
||
func (e *Service) scoreReleaseGroupCandidate(
|
||
q string,
|
||
rg *MBReleaseGroup,
|
||
clicks map[string]searchClick,
|
||
) float64 {
|
||
title := strings.ToLower(rg.Title)
|
||
credit := strings.ToLower(rg.ArtistCredit)
|
||
qn := normalizeForMatch(q)
|
||
tn := normalizeForMatch(rg.Title)
|
||
cn := normalizeForMatch(rg.ArtistCredit)
|
||
|
||
score := 0.0
|
||
|
||
switch {
|
||
case tn == qn:
|
||
score += fwExactTitle
|
||
case cn == qn && len(qn) >= 3: //nolint:mnd
|
||
score += fwExactArtist
|
||
case strings.HasPrefix(title, q):
|
||
score += fwPrefixTitle
|
||
case containsWord(title, q):
|
||
score += fwContainsWord
|
||
case strings.Contains(title, q):
|
||
score += fwContainsAny
|
||
}
|
||
|
||
score += fwListenLog * normLog(rg.Popularity)
|
||
score += fwListenerLog * normLog(rg.ListenerCount)
|
||
|
||
if rg.InLibrary {
|
||
score += fwInLibrary
|
||
}
|
||
|
||
// Penalize "Various Artists" compilations — they tend to dominate
|
||
// covers searches without being what the user wants.
|
||
if strings.Contains(credit, "various artists") {
|
||
score *= 0.5 //nolint:mnd
|
||
}
|
||
|
||
if cb := clicks[rg.MBID]; cb.count > 0 {
|
||
score += clickFeature(cb)
|
||
}
|
||
|
||
return score
|
||
}
|
||
|
||
// scoreRecordingCandidate computes the featurized quality score for
|
||
// a recording top-result candidate.
|
||
func (e *Service) scoreRecordingCandidate(
|
||
q string,
|
||
r *MBRecording,
|
||
clicks map[string]searchClick,
|
||
) float64 {
|
||
title := strings.ToLower(r.Title)
|
||
qn := normalizeForMatch(q)
|
||
tn := normalizeForMatch(r.Title)
|
||
cn := normalizeForMatch(r.ArtistCredit)
|
||
|
||
score := 0.0
|
||
|
||
switch {
|
||
case tn == qn:
|
||
score += fwExactTitle
|
||
case cn == qn && len(qn) >= 3: //nolint:mnd
|
||
score += fwExactArtist
|
||
case strings.HasPrefix(title, q):
|
||
score += fwPrefixTitle
|
||
case containsWord(title, q):
|
||
score += fwContainsWord
|
||
case strings.Contains(title, q):
|
||
score += fwContainsAny
|
||
}
|
||
|
||
score += fwListenLog * normLog(r.Popularity)
|
||
score += fwListenerLog * normLog(r.ListenerCount)
|
||
|
||
if r.InLibrary {
|
||
score += fwInLibrary
|
||
}
|
||
|
||
if cb := clicks[r.MBID]; cb.count > 0 {
|
||
score += clickFeature(cb)
|
||
}
|
||
|
||
return score
|
||
}
|
||
|
||
// scoreExactMatch computes a featurized quality score for a
|
||
// candidate sourced from ExactMatches. Always assigns the exact
|
||
// match feature bonus on top of the standard quality features so
|
||
// that exact matches reliably outrank fuzzy ones.
|
||
func (e *Service) scoreExactMatch(
|
||
q string,
|
||
m *SearchIndexResult,
|
||
clicks map[string]searchClick,
|
||
) float64 {
|
||
title := strings.ToLower(m.Title)
|
||
credit := strings.ToLower(m.ArtistName)
|
||
|
||
score := 0.0
|
||
|
||
if title == q {
|
||
score += fwExactTitle
|
||
} else if credit == q {
|
||
score += fwExactArtist
|
||
} else {
|
||
// Shouldn't happen — ExactMatches only returns rows whose
|
||
// title or artist matches. Defensive fallback.
|
||
score += fwContainsWord
|
||
}
|
||
|
||
score += fwListenLog * normLog(m.Popularity)
|
||
score += fwListenerLog * normLog(m.ListenerCount)
|
||
|
||
if m.InLibrary || m.LocalArtistID > 0 || m.LocalReleaseGroupID > 0 || m.LocalRecordingID > 0 {
|
||
score += fwInLibrary
|
||
}
|
||
|
||
if cb := clicks[m.MBID]; cb.count > 0 {
|
||
score += clickFeature(cb)
|
||
}
|
||
|
||
return score
|
||
}
|
||
|
||
// computeIntentPrior derives a category probability distribution
|
||
// from the query shape and the catalog signals available in the
|
||
// candidate pool. Returns weights summing to ~1.0.
|
||
//
|
||
// Strategy: start with a uniform prior, then apply signal-based
|
||
// adjustments. The strongest signals (exact name match against a
|
||
// popular artist, dominant track-cover-wave pattern) bias the prior
|
||
// hard; weaker signals (query length, listen-count distribution)
|
||
// nudge it. Finally normalize to a probability distribution.
|
||
//
|
||
// The exactCandidates parameter is the list of candidates that hit
|
||
// an exact-match feature (either via the local index ExactMatches
|
||
// retrieval or via the MB result-list scan in gatherTopCandidates).
|
||
// These provide the strongest evidence we have for "the user means
|
||
// this category" and dominate weaker signals.
|
||
func (e *Service) computeIntentPrior(
|
||
q string,
|
||
result *MBSearchResult,
|
||
exactMatches []SearchIndexResult,
|
||
exactCandidates []topCandidate,
|
||
) intentPrior {
|
||
// Start with a slight lean toward recordings — most music
|
||
// searches in practice are for songs. Mild enough that
|
||
// other signals can override.
|
||
weights := intentPrior{
|
||
artist: 1.0,
|
||
album: 1.0,
|
||
recording: 1.2, //nolint:mnd
|
||
}
|
||
|
||
// Signal: query length (word count). Single-word queries skew
|
||
// strongly artist; long queries skew strongly toward
|
||
// titles (album or recording).
|
||
wordCount := len(strings.Fields(q))
|
||
|
||
switch {
|
||
case wordCount == 1:
|
||
weights.artist *= 2.0 //nolint:mnd
|
||
weights.album *= 0.7 //nolint:mnd
|
||
weights.recording *= 0.7 //nolint:mnd
|
||
case wordCount >= 4: //nolint:mnd
|
||
weights.artist *= 0.5 //nolint:mnd
|
||
weights.album *= 1.2 //nolint:mnd
|
||
weights.recording *= 1.3 //nolint:mnd
|
||
}
|
||
|
||
// Signal: exact matches in the local index. An exact match
|
||
// against a popular artist is the strongest evidence we
|
||
// have for "the user means this artist". Scale by listener
|
||
// count so a popular exact match dominates and an obscure
|
||
// one doesn't move the needle.
|
||
for _, m := range exactMatches {
|
||
if !isExactNameMatch(q, m.Title) && !isExactNameMatch(q, m.ArtistName) {
|
||
continue
|
||
}
|
||
|
||
// Confidence boost scales with log listener count.
|
||
boost := 1.0 + 1.5*normLog(m.ListenerCount) //nolint:mnd
|
||
|
||
switch m.EntityType {
|
||
case "artist":
|
||
weights.artist *= boost
|
||
case "release_group":
|
||
weights.album *= boost
|
||
case "recording":
|
||
weights.recording *= boost
|
||
}
|
||
}
|
||
|
||
// Signal: exact-match candidates discovered in the MB result
|
||
// list (Source 1b/2b/3b in gatherTopCandidates). These cover
|
||
// the case where the local index doesn't have the entity but
|
||
// MB does — e.g. Blue October's "Calling You" when Blue
|
||
// October isn't yet a known artist. Same scaling as
|
||
// index-sourced exact matches.
|
||
for _, c := range exactCandidates {
|
||
var listeners int
|
||
switch c.category {
|
||
case "artist":
|
||
listeners = artistListenerByMBID(result.Artists, c.topResult.MBID)
|
||
case "release_group":
|
||
listeners = rgListenerByMBID(result.ReleaseGroups, c.topResult.MBID)
|
||
case "recording":
|
||
listeners = recListenerByMBID(result.Recordings, c.topResult.MBID)
|
||
}
|
||
|
||
boost := 1.0 + 1.0*normLog(listeners) //nolint:mnd
|
||
|
||
switch c.category {
|
||
case "artist":
|
||
weights.artist *= boost
|
||
case "release_group":
|
||
weights.album *= boost
|
||
case "recording":
|
||
weights.recording *= boost
|
||
}
|
||
}
|
||
|
||
// Signal: many recordings in the result list with the same
|
||
// title as the query → cover-wave pattern → strong recording.
|
||
titleMatches := 0
|
||
for _, r := range result.Recordings {
|
||
if isExactNameMatch(q, r.Title) {
|
||
titleMatches++
|
||
}
|
||
}
|
||
|
||
if titleMatches >= 5 { //nolint:mnd
|
||
weights.recording *= 1.8 //nolint:mnd
|
||
} else if titleMatches >= 2 { //nolint:mnd
|
||
weights.recording *= 1.3 //nolint:mnd
|
||
}
|
||
|
||
// Signal: aggregate listener count per category in the
|
||
// candidate pool. Sum the top 5 per category and use the
|
||
// proportional split as a soft nudge. Recordings naturally
|
||
// have higher listen counts than albums (each play increments
|
||
// the recording, not the album), so we use *listener* count
|
||
// rather than *listen* count to dampen that bias.
|
||
artistListeners := sumTopListeners(artistListenerCounts(result.Artists), 5) //nolint:mnd
|
||
albumListeners := sumTopListeners(rgListenerCounts(result.ReleaseGroups), 5) //nolint:mnd
|
||
recListeners := sumTopListeners(recListenerCounts(result.Recordings), 5) //nolint:mnd
|
||
|
||
totalListeners := artistListeners + albumListeners + recListeners
|
||
if totalListeners > 0 {
|
||
// Apply as a 0.5x nudge so it doesn't override stronger
|
||
// signals. We'd rather trust shape and exact matches
|
||
// than raw listener distributions.
|
||
weights.artist *= 1.0 + 0.5*float64(artistListeners)/float64(totalListeners) //nolint:mnd
|
||
weights.album *= 1.0 + 0.5*float64(albumListeners)/float64(totalListeners) //nolint:mnd
|
||
weights.recording *= 1.0 + 0.5*float64(recListeners)/float64(totalListeners) //nolint:mnd
|
||
}
|
||
|
||
// Normalize to a probability distribution.
|
||
total := weights.artist + weights.album + weights.recording
|
||
if total <= 0 {
|
||
return intentPrior{artist: 1.0 / 3.0, album: 1.0 / 3.0, recording: 1.0 / 3.0} //nolint:mnd
|
||
}
|
||
|
||
return intentPrior{
|
||
artist: weights.artist / total,
|
||
album: weights.album / total,
|
||
recording: weights.recording / total,
|
||
}
|
||
}
|
||
|
||
// artistListenerByMBID returns the listener count for the artist
|
||
// with the given MBID, or 0 when not found.
|
||
func artistListenerByMBID(arts []MBArtist, mbid string) int {
|
||
for _, a := range arts {
|
||
if a.MBID == mbid {
|
||
return a.ListenerCount
|
||
}
|
||
}
|
||
|
||
return 0
|
||
}
|
||
|
||
func rgListenerByMBID(rgs []MBReleaseGroup, mbid string) int {
|
||
for _, rg := range rgs {
|
||
if rg.MBID == mbid {
|
||
return rg.ListenerCount
|
||
}
|
||
}
|
||
|
||
return 0
|
||
}
|
||
|
||
func recListenerByMBID(recs []MBRecording, mbid string) int {
|
||
for _, r := range recs {
|
||
if r.MBID == mbid {
|
||
return r.ListenerCount
|
||
}
|
||
}
|
||
|
||
return 0
|
||
}
|
||
|
||
// priorConfidence returns the difference between the largest and
|
||
// second-largest values in the prior, as a quick proxy for "how
|
||
// sure is the prior about its top pick". Range is 0 (totally flat,
|
||
// i.e. uniform 1/3) to 1 (one category at 1.0, others at 0).
|
||
func priorConfidence(p intentPrior) float64 {
|
||
vals := [3]float64{p.artist, p.album, p.recording}
|
||
|
||
maxVal := vals[0]
|
||
for _, v := range vals[1:] {
|
||
if v > maxVal {
|
||
maxVal = v
|
||
}
|
||
}
|
||
|
||
secondMax := 0.0
|
||
for _, v := range vals {
|
||
if v < maxVal && v > secondMax {
|
||
secondMax = v
|
||
}
|
||
}
|
||
|
||
return maxVal - secondMax
|
||
}
|
||
|
||
// normLog returns log10(n+1) / log10(maxScale+1), clamped to [0, 1].
|
||
// maxScale is a fixed reference point so the function is stable
|
||
// across queries — different from popRank which normalizes to a
|
||
// dynamic per-query max.
|
||
func normLog(n int) float64 {
|
||
if n <= 0 {
|
||
return 0
|
||
}
|
||
|
||
const maxScale = 50_000_000 // top-tier artists have ~10-150M listens
|
||
|
||
v := math.Log10(float64(n)+1) / math.Log10(maxScale+1) //nolint:mnd
|
||
if v > 1.0 {
|
||
return 1.0
|
||
}
|
||
|
||
return v
|
||
}
|
||
|
||
// clickFeature returns the additive feature contribution from a
|
||
// per-query click record. Bounded so a click streak can't
|
||
// dominate the rest of the score.
|
||
func clickFeature(c searchClick) float64 {
|
||
daysSince := time.Since(c.lastClicked).Hours() / 24.0 //nolint:mnd
|
||
recency := 1.0 / (1.0 + daysSince/topResultsClickDecay)
|
||
boost := math.Log2(float64(c.count)+1) * recency * 0.3 //nolint:mnd
|
||
|
||
if boost > 0.6 { //nolint:mnd
|
||
return 0.6
|
||
}
|
||
|
||
return boost
|
||
}
|
||
|
||
// artistListenerCounts and friends extract the per-entity listener
|
||
// count slice for the listener-distribution prior signal.
|
||
func artistListenerCounts(arts []MBArtist) []int {
|
||
out := make([]int, len(arts))
|
||
for i, a := range arts {
|
||
out[i] = a.ListenerCount
|
||
}
|
||
|
||
return out
|
||
}
|
||
|
||
func rgListenerCounts(rgs []MBReleaseGroup) []int {
|
||
out := make([]int, len(rgs))
|
||
for i, rg := range rgs {
|
||
out[i] = rg.ListenerCount
|
||
}
|
||
|
||
return out
|
||
}
|
||
|
||
func recListenerCounts(recs []MBRecording) []int {
|
||
out := make([]int, len(recs))
|
||
for i, r := range recs {
|
||
out[i] = r.ListenerCount
|
||
}
|
||
|
||
return out
|
||
}
|
||
|
||
// sumTopListeners returns the sum of the top n entries in xs.
|
||
// Used by the listener-distribution prior signal.
|
||
func sumTopListeners(xs []int, n int) int {
|
||
if len(xs) == 0 {
|
||
return 0
|
||
}
|
||
|
||
sorted := make([]int, len(xs))
|
||
copy(sorted, xs)
|
||
|
||
sort.Slice(sorted, func(i, j int) bool {
|
||
return sorted[i] > sorted[j]
|
||
})
|
||
|
||
if n > len(sorted) {
|
||
n = len(sorted)
|
||
}
|
||
|
||
sum := 0
|
||
for i := 0; i < n; i++ {
|
||
sum += sorted[i]
|
||
}
|
||
|
||
return sum
|
||
}
|
||
// containsWord checks if text contains word as a whole word bounded
|
||
// by spaces, hyphens, or string boundaries.
|
||
func containsWord(text, word string) bool {
|
||
idx := strings.Index(text, word)
|
||
if idx < 0 {
|
||
return false
|
||
}
|
||
|
||
// Check left boundary.
|
||
if idx > 0 {
|
||
c := text[idx-1]
|
||
if c != ' ' && c != '-' && c != '(' && c != '[' {
|
||
return false
|
||
}
|
||
}
|
||
|
||
// Check right boundary.
|
||
end := idx + len(word)
|
||
if end < len(text) {
|
||
c := text[end]
|
||
if c != ' ' && c != '-' && c != ')' && c != ']' {
|
||
return false
|
||
}
|
||
}
|
||
|
||
return true
|
||
}
|
||
|
||
// isExactNameMatch returns true when the (already lowercased) query
|
||
// is equal to the (raw-cased) name after lowercasing and trimming.
|
||
// Punctuation is normalized so "Party in the U.S.A." matches
|
||
// "party in the usa". Used by the top-results pipeline to find
|
||
// exact matches anywhere in the main result lists, not just in the
|
||
// top-N positions the main rerank produced.
|
||
func isExactNameMatch(q, name string) bool {
|
||
if name == "" {
|
||
return false
|
||
}
|
||
|
||
return normalizeForMatch(name) == normalizeForMatch(q)
|
||
}
|
||
|
||
// isCompositeMatch returns true when the query contains both `title`
|
||
// and `artist` as normalized substrings — e.g. "calling you blue
|
||
// october" composes "calling you" + "blue october" so the user
|
||
// probably wants Blue October's "Calling You". Both fragments must
|
||
// be at least 3 characters to be considered.
|
||
//
|
||
// This is the heuristic version of entity linking: instead of
|
||
// training a model to identify "title + artist" multi-entity
|
||
// queries, we just notice when a candidate's title and artist both
|
||
// appear inside the user's query.
|
||
func isCompositeMatch(q, title, artist string) bool {
|
||
if len(title) < 3 || len(artist) < 3 { //nolint:mnd
|
||
return false
|
||
}
|
||
|
||
qn := normalizeForMatch(q)
|
||
tn := normalizeForMatch(title)
|
||
an := normalizeForMatch(artist)
|
||
|
||
if tn == "" || an == "" || qn == "" {
|
||
return false
|
||
}
|
||
|
||
// Both fragments must appear in the query. Order doesn't
|
||
// matter — "calling you blue october" and "blue october
|
||
// calling you" should both match.
|
||
return strings.Contains(qn, tn) && strings.Contains(qn, an)
|
||
}
|
||
|
||
// normalizeForMatch lowercases, trims, and strips ASCII punctuation
|
||
// other than internal whitespace so titles like "Party in the U.S.A.",
|
||
// "Party In the U.S.A", and "party in the usa" all collapse to the
|
||
// same normalized form. Cheap O(n) — no regex.
|
||
func normalizeForMatch(s string) string {
|
||
s = strings.ToLower(strings.TrimSpace(s))
|
||
|
||
var b strings.Builder
|
||
b.Grow(len(s))
|
||
|
||
prevSpace := false
|
||
|
||
for _, r := range s {
|
||
switch {
|
||
case r >= 'a' && r <= 'z',
|
||
r >= '0' && r <= '9',
|
||
r >= 0x80: // keep non-ASCII as-is
|
||
b.WriteRune(r)
|
||
prevSpace = false
|
||
case r == ' ' || r == '\t':
|
||
if !prevSpace && b.Len() > 0 {
|
||
b.WriteByte(' ')
|
||
prevSpace = true
|
||
}
|
||
default:
|
||
// Drop punctuation entirely (not even replaced with
|
||
// a space). This collapses "U.S.A." to "usa" so it
|
||
// matches the dot-less form.
|
||
}
|
||
}
|
||
|
||
out := b.String()
|
||
if prevSpace && len(out) > 0 {
|
||
out = out[:len(out)-1]
|
||
}
|
||
|
||
return out
|
||
}
|
||
|
||
type searchClick struct {
|
||
count int
|
||
lastClicked time.Time
|
||
}
|
||
|
||
// getSearchClicks returns click history for a query.
|
||
func (e *Service) getSearchClicks(query string) map[string]searchClick {
|
||
rows, err := e.db.QueryContext(
|
||
"SELECT entity_mbid, click_count, last_clicked FROM search_clicks WHERE query = ?",
|
||
query,
|
||
)
|
||
if err != nil {
|
||
return nil
|
||
}
|
||
|
||
defer func() { _ = rows.Close() }()
|
||
|
||
result := make(map[string]searchClick)
|
||
|
||
for rows.Next() {
|
||
var mbid string
|
||
var count int
|
||
var lastClicked time.Time
|
||
|
||
if err := rows.Scan(&mbid, &count, &lastClicked); err == nil {
|
||
result[mbid] = searchClick{count: count, lastClicked: lastClicked}
|
||
}
|
||
}
|
||
|
||
return result
|
||
}
|
||
|
||
// RecordSearchClick records that the user clicked a search result.
|
||
// Called from the frontend when any search result is clicked.
|
||
func (e *Service) RecordSearchClick(query, mbid, entityType string) {
|
||
if query == "" || mbid == "" {
|
||
return
|
||
}
|
||
|
||
q := strings.ToLower(strings.TrimSpace(query))
|
||
|
||
_, _ = e.db.ExecContext(`
|
||
INSERT INTO search_clicks (query, entity_mbid, entity_type, click_count, last_clicked)
|
||
VALUES (?, ?, ?, 1, CURRENT_TIMESTAMP)
|
||
ON CONFLICT(query, entity_mbid) DO UPDATE SET
|
||
click_count = click_count + 1,
|
||
last_clicked = CURRENT_TIMESTAMP
|
||
`, q, mbid, entityType)
|
||
}
|
||
|
||
// blendedScore computes relevanceWeight*relevance + popularityWeight*logPop.
|
||
// relevance is 0–1. listenCount is raw; maxListenCount is the
|
||
// maximum in the result set (for normalization).
|
||
func blendedScore(relevance float64, listenCount, maxListenCount int) float64 {
|
||
return blendedScoreFull(relevance, listenCount, maxListenCount, 0.0)
|
||
}
|
||
|
||
// blendedScoreFull computes the weighted blend of relevance, popularity,
|
||
// and personalization. personalization is 0.0–1.0.
|
||
func blendedScoreFull(relevance float64, listenCount, maxListenCount int, personalization float64) float64 {
|
||
effectiveMax := maxListenCount
|
||
if effectiveMax < 100_000 { //nolint:mnd
|
||
effectiveMax = 100_000
|
||
}
|
||
|
||
logPop := math.Log10(float64(listenCount)+1) / math.Log10(float64(effectiveMax)+1)
|
||
|
||
return relevanceWeight*relevance + popularityWeight*logPop + personalizationWeight*personalization
|
||
}
|
||
|
||
// dynamicSearchLimit computes the number of results to request from
|
||
// MB based on the total match count. Returns at least mbSearchLimit
|
||
// and at most mbSearchMaxLimit. Aims for ~15% of total matches so
|
||
// the ranking pipeline has enough candidates to surface popular
|
||
// results that MB's text relevance alone would bury.
|
||
func dynamicSearchLimit(totalMatches int) int {
|
||
if totalMatches <= mbSearchLimit {
|
||
return mbSearchLimit
|
||
}
|
||
|
||
// 15% of total matches, but floor to mbSearchLimit and
|
||
// cap to mbSearchMaxLimit (and MB's API max of 100).
|
||
want := totalMatches * 15 / 100 //nolint:mnd
|
||
if want < mbSearchLimit {
|
||
want = mbSearchLimit
|
||
}
|
||
|
||
if want > mbSearchMaxLimit {
|
||
want = mbSearchMaxLimit
|
||
}
|
||
|
||
return want
|
||
}
|
||
|
||
// maxListenCount returns the highest listen count in the map.
|
||
func maxListenCount(pop map[string]int) int {
|
||
maxVal := 0
|
||
|
||
for _, v := range pop {
|
||
if v > maxVal {
|
||
maxVal = v
|
||
}
|
||
}
|
||
|
||
return maxVal
|
||
}
|
||
|
||
// listenCounts extracts a simple mbid→listenCount map from PopularityData.
|
||
func listenCounts(pop map[string]PopularityData) map[string]int {
|
||
out := make(map[string]int, len(pop))
|
||
for mbid, d := range pop {
|
||
out[mbid] = d.ListenCount
|
||
}
|
||
|
||
return out
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Lucene query building
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// luceneSpecialChars are characters that have special meaning in
|
||
// Lucene query syntax and must be escaped in user input.
|
||
var luceneSpecialChars = strings.NewReplacer( //nolint:gochecknoglobals
|
||
`\`, `\\`,
|
||
`+`, `\+`,
|
||
`-`, `\-`,
|
||
`!`, `\!`,
|
||
`(`, `\(`,
|
||
`)`, `\)`,
|
||
`{`, `\{`,
|
||
`}`, `\}`,
|
||
`[`, `\[`,
|
||
`]`, `\]`,
|
||
`^`, `\^`,
|
||
`"`, `\"`,
|
||
`~`, `\~`,
|
||
`*`, `\*`,
|
||
`?`, `\?`,
|
||
`:`, `\:`,
|
||
`/`, `\/`,
|
||
)
|
||
|
||
// buildLuceneQuery converts a user's search input into a Lucene
|
||
// AND query with a wildcard on the last term for type-ahead.
|
||
//
|
||
// Examples:
|
||
//
|
||
// "radiohead" → "radiohead*"
|
||
// "the teenagers" → "the AND teenagers*"
|
||
// "florence machine" → "florence AND machine*"
|
||
// "ac/dc" → "ac\/dc*"
|
||
//
|
||
// This eliminates the common-word pollution problem: "the teenagers"
|
||
// no longer matches "The Beatles" (which only contains "the").
|
||
// The trailing wildcard enables prefix matching as the user types.
|
||
func buildLuceneQuery(input string) string {
|
||
words := strings.Fields(strings.TrimSpace(input))
|
||
if len(words) == 0 {
|
||
return ""
|
||
}
|
||
|
||
// Escape special Lucene characters in each word.
|
||
for i, w := range words {
|
||
words[i] = luceneSpecialChars.Replace(w)
|
||
}
|
||
|
||
if len(words) == 1 {
|
||
return words[0] + "*"
|
||
}
|
||
|
||
// AND all terms, wildcard on the last (type-ahead).
|
||
var b strings.Builder
|
||
|
||
for i, w := range words {
|
||
if i > 0 {
|
||
b.WriteString(" AND ")
|
||
}
|
||
|
||
b.WriteString(w)
|
||
|
||
if i == len(words)-1 {
|
||
b.WriteByte('*')
|
||
}
|
||
}
|
||
|
||
return b.String()
|
||
}
|
||
|
||
// buildLuceneQueryWithArtist builds a Lucene query that searches
|
||
// both the entity's own field (title) and the artist credit field.
|
||
// For "queen": (releasegroup:queen* OR artist:queen*)
|
||
// This ensures searches return results BY the artist, not just
|
||
// results with the query in the title.
|
||
func buildLuceneQueryWithArtist(input, entityField, artistField string) string {
|
||
words := strings.Fields(strings.TrimSpace(input))
|
||
if len(words) == 0 {
|
||
return ""
|
||
}
|
||
|
||
for i, w := range words {
|
||
words[i] = luceneSpecialChars.Replace(w)
|
||
}
|
||
|
||
// Build the base query terms.
|
||
base := buildLuceneQuery(input)
|
||
|
||
// Single word: (field:word* OR artist:word*)
|
||
if len(words) == 1 {
|
||
return "(" + entityField + ":" + base + " OR " + artistField + ":" + base + ")"
|
||
}
|
||
|
||
// Multi-word: (field:(term1 AND term2*) OR artist:(term1 AND term2*))
|
||
return "(" + entityField + ":(" + base + ") OR " + artistField + ":(" + base + "))"
|
||
}
|