refactor: remove outdated comments in GetSimilarSongs methods

Signed-off-by: Deluan <deluan@navidrome.org>

adapters/lastfm/agent.go

@@ -192,6 +192,26 @@ func (l *lastfmAgent) GetArtistTopSongs(ctx context.Context, id, artistName, mbi
 	return res, nil
 }
 
+func (l *lastfmAgent) GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]agents.Song, error) {
+	resp, err := l.callTrackGetSimilar(ctx, name, artist, count)
+	if err != nil {
+		return nil, err
+	}
+	if len(resp) == 0 {
+		return nil, agents.ErrNotFound
+	}
+	res := make([]agents.Song, 0, len(resp))
+	for _, t := range resp {
+		res = append(res, agents.Song{
+			Name:       t.Name,
+			MBID:       t.MBID,
+			Artist:     t.Artist.Name,
+			ArtistMBID: t.Artist.MBID,
+		})
+	}
+	return res, nil
+}
+
 var (
 	artistOpenGraphQuery = cascadia.MustCompile(`html > head > meta[property="og:image"]`)
 	artistIgnoredImage   = "2a96cbd8b46e442fc41c2b86b821562f" // Last.fm artist placeholder image name
@@ -290,6 +310,15 @@ func (l *lastfmAgent) callArtistGetTopTracks(ctx context.Context, artistName str
 	return t.Track, nil
 }
 
+func (l *lastfmAgent) callTrackGetSimilar(ctx context.Context, name, artist string, count int) ([]SimilarTrack, error) {
+	s, err := l.client.trackGetSimilar(ctx, name, artist, count)
+	if err != nil {
+		log.Error(ctx, "Error calling LastFM/track.getSimilar", "track", name, "artist", artist, err)
+		return nil, err
+	}
+	return s.Track, nil
+}
+
 func (l *lastfmAgent) getArtistForScrobble(track *model.MediaFile, role model.Role, displayName string) string {
 	if conf.Server.LastFM.ScrobbleFirstArtistOnly && len(track.Participants[role]) > 0 {
 		return track.Participants[role][0].Name

adapters/lastfm/agent_test.go

@@ -177,6 +177,54 @@ var _ = Describe("lastfmAgent", func() {
 		})
 	})
 
+	Describe("GetSimilarSongsByTrack", func() {
+		var agent *lastfmAgent
+		var httpClient *tests.FakeHttpClient
+		BeforeEach(func() {
+			httpClient = &tests.FakeHttpClient{}
+			client := newClient("API_KEY", "SECRET", "pt", httpClient)
+			agent = lastFMConstructor(ds)
+			agent.client = client
+		})
+
+		It("returns similar songs", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+			Expect(agent.GetSimilarSongsByTrack(ctx, "123", "Just Can't Get Enough", "Depeche Mode", "", 5)).To(Equal([]agents.Song{
+				{Name: "Dreaming of Me", MBID: "027b553e-7c74-3ed4-a95e-1d4fea51f174", Artist: "Depeche Mode", ArtistMBID: "8538e728-ca0b-4321-b7e5-cff6565dd4c0"},
+				{Name: "Everything Counts", MBID: "5a5a3ca4-bdb8-4641-a674-9b54b9b319a6", Artist: "Depeche Mode", ArtistMBID: "8538e728-ca0b-4321-b7e5-cff6565dd4c0"},
+				{Name: "Don't You Want Me", MBID: "", Artist: "The Human League", ArtistMBID: "7adaabfb-acfb-47bc-8c7c-59471c2f0db8"},
+				{Name: "Tainted Love", MBID: "", Artist: "Soft Cell", ArtistMBID: "7fb50287-029d-47cc-825a-235ca28024b2"},
+				{Name: "Blue Monday", MBID: "727e84c6-1b56-31dd-a958-a5f46305cec0", Artist: "New Order", ArtistMBID: "f1106b17-dcbb-45f6-b938-199ccfab50cc"},
+			}))
+			Expect(httpClient.RequestCount).To(Equal(1))
+			Expect(httpClient.SavedRequest.URL.Query().Get("track")).To(Equal("Just Can't Get Enough"))
+			Expect(httpClient.SavedRequest.URL.Query().Get("artist")).To(Equal("Depeche Mode"))
+		})
+
+		It("returns ErrNotFound when no similar songs found", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.unknown.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+			_, err := agent.GetSimilarSongsByTrack(ctx, "123", "UnknownTrack", "UnknownArtist", "", 3)
+			Expect(err).To(MatchError(agents.ErrNotFound))
+			Expect(httpClient.RequestCount).To(Equal(1))
+		})
+
+		It("returns an error if Last.fm call fails", func() {
+			httpClient.Err = errors.New("error")
+			_, err := agent.GetSimilarSongsByTrack(ctx, "123", "Believe", "Cher", "", 3)
+			Expect(err).To(HaveOccurred())
+			Expect(httpClient.RequestCount).To(Equal(1))
+		})
+
+		It("returns an error if Last.fm call returns an error", func() {
+			httpClient.Res = http.Response{Body: io.NopCloser(bytes.NewBufferString(lastfmError3)), StatusCode: 200}
+			_, err := agent.GetSimilarSongsByTrack(ctx, "123", "Believe", "Cher", "", 3)
+			Expect(err).To(HaveOccurred())
+			Expect(httpClient.RequestCount).To(Equal(1))
+		})
+	})
+
 	Describe("Scrobbling", func() {
 		var agent *lastfmAgent
 		var httpClient *tests.FakeHttpClient

adapters/lastfm/client.go

@@ -95,6 +95,19 @@ func (c *client) artistGetTopTracks(ctx context.Context, name string, limit int)
 	return &response.TopTracks, nil
 }
 
+func (c *client) trackGetSimilar(ctx context.Context, name, artist string, limit int) (*SimilarTracks, error) {
+	params := url.Values{}
+	params.Add("method", "track.getSimilar")
+	params.Add("track", name)
+	params.Add("artist", artist)
+	params.Add("limit", strconv.Itoa(limit))
+	response, err := c.makeRequest(ctx, http.MethodGet, params, false)
+	if err != nil {
+		return nil, err
+	}
+	return &response.SimilarTracks, nil
+}
+
 func (c *client) GetToken(ctx context.Context) (string, error) {
 	params := url.Values{}
 	params.Add("method", "auth.getToken")

adapters/lastfm/client_test.go

@@ -121,6 +121,30 @@ var _ = Describe("client", func() {
 		})
 	})
 
+	Describe("trackGetSimilar", func() {
+		It("returns similar tracks for a successful response", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+
+			similar, err := client.trackGetSimilar(context.Background(), "Just Can't Get Enough", "Depeche Mode", 5)
+			Expect(err).To(BeNil())
+			Expect(len(similar.Track)).To(Equal(5))
+			Expect(similar.Track[0].Name).To(Equal("Dreaming of Me"))
+			Expect(similar.Track[0].Artist.Name).To(Equal("Depeche Mode"))
+			Expect(similar.Track[0].Match).To(Equal(1.0))
+			Expect(httpClient.SavedRequest.URL.String()).To(Equal(apiBaseUrl + "?api_key=API_KEY&artist=Depeche+Mode&format=json&limit=5&method=track.getSimilar&track=Just+Can%27t+Get+Enough"))
+		})
+
+		It("returns empty list when no similar tracks found", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.unknown.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+
+			similar, err := client.trackGetSimilar(context.Background(), "UnknownTrack", "UnknownArtist", 3)
+			Expect(err).To(BeNil())
+			Expect(similar.Track).To(BeEmpty())
+		})
+	})
+
 	Describe("GetToken", func() {
 		It("returns a token when the request is successful", func() {
 			httpClient.Res = http.Response{

adapters/lastfm/responses.go

@@ -5,6 +5,7 @@ type Response struct {
 	SimilarArtists SimilarArtists `json:"similarartists"`
 	TopTracks      TopTracks      `json:"toptracks"`
 	Album          Album          `json:"album"`
+	SimilarTracks  SimilarTracks  `json:"similartracks"`
 	Error          int            `json:"error"`
 	Message        string         `json:"message"`
 	Token          string         `json:"token"`
@@ -59,6 +60,28 @@ type TopTracks struct {
 	Attr  Attr    `json:"@attr"`
 }
 
+type SimilarTracks struct {
+	Track []SimilarTrack `json:"track"`
+	Attr  SimilarAttr    `json:"@attr"`
+}
+
+type SimilarTrack struct {
+	Name   string             `json:"name"`
+	MBID   string             `json:"mbid"`
+	Match  float64            `json:"match"`
+	Artist SimilarTrackArtist `json:"artist"`
+}
+
+type SimilarTrackArtist struct {
+	Name string `json:"name"`
+	MBID string `json:"mbid"`
+}
+
+type SimilarAttr struct {
+	Artist string `json:"artist"`
+	Track  string `json:"track"`
+}
+
 type Session struct {
 	Name       string `json:"name"`
 	Key        string `json:"key"`

core/agents/agents.go

@@ -22,6 +22,8 @@ type PluginLoader interface {
 	LoadMediaAgent(name string) (Interface, bool)
 }
 
+// Agents is a meta-agent that aggregates multiple built-in and plugin agents. It tries each enabled agent in order
+// until one returns valid data.
 type Agents struct {
 	ds           model.DataStore
 	pluginLoader PluginLoader
@@ -129,26 +131,14 @@ func (a *Agents) GetArtistMBID(ctx context.Context, id string, name string) (str
 	case consts.VariousArtistsID:
 		return "", nil
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentMethod(ctx, a, "GetArtistMBID", func(ag Interface) (string, error) {
 		retriever, ok := ag.(ArtistMBIDRetriever)
 		if !ok {
-			continue
+			return "", ErrNotFound
 		}
-		mbid, err := retriever.GetArtistMBID(ctx, id, name)
-		if mbid != "" && err == nil {
-			log.Debug(ctx, "Got MBID", "agent", ag.AgentName(), "artist", name, "mbid", mbid, "elapsed", time.Since(start))
-			return mbid, nil
-		}
-	}
-	return "", ErrNotFound
+		return retriever.GetArtistMBID(ctx, id, name)
+	})
 }
 
 func (a *Agents) GetArtistURL(ctx context.Context, id, name, mbid string) (string, error) {
@@ -158,26 +148,14 @@ func (a *Agents) GetArtistURL(ctx context.Context, id, name, mbid string) (strin
 	case consts.VariousArtistsID:
 		return "", nil
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentMethod(ctx, a, "GetArtistURL", func(ag Interface) (string, error) {
 		retriever, ok := ag.(ArtistURLRetriever)
 		if !ok {
-			continue
+			return "", ErrNotFound
 		}
-		url, err := retriever.GetArtistURL(ctx, id, name, mbid)
-		if url != "" && err == nil {
-			log.Debug(ctx, "Got External Url", "agent", ag.AgentName(), "artist", name, "url", url, "elapsed", time.Since(start))
-			return url, nil
-		}
-	}
-	return "", ErrNotFound
+		return retriever.GetArtistURL(ctx, id, name, mbid)
+	})
 }
 
 func (a *Agents) GetArtistBiography(ctx context.Context, id, name, mbid string) (string, error) {
@@ -187,26 +165,14 @@ func (a *Agents) GetArtistBiography(ctx context.Context, id, name, mbid string)
 	case consts.VariousArtistsID:
 		return "", nil
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentMethod(ctx, a, "GetArtistBiography", func(ag Interface) (string, error) {
 		retriever, ok := ag.(ArtistBiographyRetriever)
 		if !ok {
-			continue
+			return "", ErrNotFound
 		}
-		bio, err := retriever.GetArtistBiography(ctx, id, name, mbid)
-		if err == nil {
-			log.Debug(ctx, "Got Biography", "agent", ag.AgentName(), "artist", name, "len", len(bio), "elapsed", time.Since(start))
-			return bio, nil
-		}
-	}
-	return "", ErrNotFound
+		return retriever.GetArtistBiography(ctx, id, name, mbid)
+	})
 }
 
 // GetSimilarArtists returns similar artists by id, name, and/or mbid. Because some artists returned from an enabled
@@ -254,26 +220,14 @@ func (a *Agents) GetArtistImages(ctx context.Context, id, name, mbid string) ([]
 	case consts.VariousArtistsID:
 		return nil, nil
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentSliceMethod(ctx, a, "GetArtistImages", func(ag Interface) ([]ExternalImage, error) {
 		retriever, ok := ag.(ArtistImageRetriever)
 		if !ok {
-			continue
+			return nil, ErrNotFound
 		}
-		images, err := retriever.GetArtistImages(ctx, id, name, mbid)
-		if len(images) > 0 && err == nil {
-			log.Debug(ctx, "Got Images", "agent", ag.AgentName(), "artist", name, "images", images, "elapsed", time.Since(start))
-			return images, nil
-		}
-	}
-	return nil, ErrNotFound
+		return retriever.GetArtistImages(ctx, id, name, mbid)
+	})
 }
 
 // GetArtistTopSongs returns top songs by id, name, and/or mbid. Because some songs returned from an enabled
@@ -288,80 +242,127 @@ func (a *Agents) GetArtistTopSongs(ctx context.Context, id, artistName, mbid str
 
 	overLimit := int(float64(count) * conf.Server.DevExternalArtistFetchMultiplier)
 
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+	return callAgentSliceMethod(ctx, a, "GetArtistTopSongs", func(ag Interface) ([]Song, error) {
 		retriever, ok := ag.(ArtistTopSongsRetriever)
 		if !ok {
-			continue
+			return nil, ErrNotFound
 		}
-		songs, err := retriever.GetArtistTopSongs(ctx, id, artistName, mbid, overLimit)
-		if len(songs) > 0 && err == nil {
-			log.Debug(ctx, "Got Top Songs", "agent", ag.AgentName(), "artist", artistName, "songs", songs, "elapsed", time.Since(start))
-			return songs, nil
-		}
-	}
-	return nil, ErrNotFound
+		return retriever.GetArtistTopSongs(ctx, id, artistName, mbid, overLimit)
+	})
 }
 
 func (a *Agents) GetAlbumInfo(ctx context.Context, name, artist, mbid string) (*AlbumInfo, error) {
 	if name == consts.UnknownAlbum {
 		return nil, ErrNotFound
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentMethod(ctx, a, "GetAlbumInfo", func(ag Interface) (*AlbumInfo, error) {
 		retriever, ok := ag.(AlbumInfoRetriever)
 		if !ok {
-			continue
+			return nil, ErrNotFound
 		}
-		album, err := retriever.GetAlbumInfo(ctx, name, artist, mbid)
-		if err == nil {
-			log.Debug(ctx, "Got Album Info", "agent", ag.AgentName(), "album", name, "artist", artist,
-				"mbid", mbid, "elapsed", time.Since(start))
-			return album, nil
-		}
-	}
-	return nil, ErrNotFound
+		return retriever.GetAlbumInfo(ctx, name, artist, mbid)
+	})
 }
 
 func (a *Agents) GetAlbumImages(ctx context.Context, name, artist, mbid string) ([]ExternalImage, error) {
 	if name == consts.UnknownAlbum {
 		return nil, ErrNotFound
 	}
+
+	return callAgentSliceMethod(ctx, a, "GetAlbumImages", func(ag Interface) ([]ExternalImage, error) {
+		retriever, ok := ag.(AlbumImageRetriever)
+		if !ok {
+			return nil, ErrNotFound
+		}
+		return retriever.GetAlbumImages(ctx, name, artist, mbid)
+	})
+}
+
+// GetSimilarSongsByTrack returns similar songs for a given track.
+func (a *Agents) GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
+	return callAgentSliceMethod(ctx, a, "GetSimilarSongsByTrack", func(ag Interface) ([]Song, error) {
+		retriever, ok := ag.(SimilarSongsByTrackRetriever)
+		if !ok {
+			return nil, ErrNotFound
+		}
+		return retriever.GetSimilarSongsByTrack(ctx, id, name, artist, mbid, count)
+	})
+}
+
+// GetSimilarSongsByAlbum returns similar songs for a given album.
+func (a *Agents) GetSimilarSongsByAlbum(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
+	return callAgentSliceMethod(ctx, a, "GetSimilarSongsByAlbum", func(ag Interface) ([]Song, error) {
+		retriever, ok := ag.(SimilarSongsByAlbumRetriever)
+		if !ok {
+			return nil, ErrNotFound
+		}
+		return retriever.GetSimilarSongsByAlbum(ctx, id, name, artist, mbid, count)
+	})
+}
+
+// GetSimilarSongsByArtist returns similar songs for a given artist.
+func (a *Agents) GetSimilarSongsByArtist(ctx context.Context, id, name, mbid string, count int) ([]Song, error) {
+	switch id {
+	case consts.UnknownArtistID:
+		return nil, ErrNotFound
+	case consts.VariousArtistsID:
+		return nil, nil
+	}
+
+	return callAgentSliceMethod(ctx, a, "GetSimilarSongsByArtist", func(ag Interface) ([]Song, error) {
+		retriever, ok := ag.(SimilarSongsByArtistRetriever)
+		if !ok {
+			return nil, ErrNotFound
+		}
+		return retriever.GetSimilarSongsByArtist(ctx, id, name, mbid, count)
+	})
+}
+
+func callAgentMethod[T comparable](ctx context.Context, agents *Agents, methodName string, fn func(Interface) (T, error)) (T, error) {
+	var zero T
 	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
+	for _, enabledAgent := range agents.getEnabledAgentNames() {
+		ag := agents.getAgent(enabledAgent)
 		if ag == nil {
 			continue
 		}
 		if utils.IsCtxDone(ctx) {
 			break
 		}
-		retriever, ok := ag.(AlbumImageRetriever)
-		if !ok {
+		result, err := fn(ag)
+		if err != nil {
+			log.Trace(ctx, "Agent method call error", "method", methodName, "agent", ag.AgentName(), "error", err)
 			continue
 		}
-		images, err := retriever.GetAlbumImages(ctx, name, artist, mbid)
-		if err != nil {
-			log.Trace(ctx, "Agent GetAlbumImages failed", "agent", ag.AgentName(), "album", name, "artist", artist, "mbid", mbid, err)
+
+		if result != zero {
+			log.Debug(ctx, "Got result", "method", methodName, "agent", ag.AgentName(), "elapsed", time.Since(start))
+			return result, nil
 		}
-		if len(images) > 0 && err == nil {
-			log.Debug(ctx, "Got Album Images", "agent", ag.AgentName(), "album", name, "artist", artist,
-				"mbid", mbid, "elapsed", time.Since(start))
-			return images, nil
+	}
+	return zero, ErrNotFound
+}
+
+func callAgentSliceMethod[T any](ctx context.Context, agents *Agents, methodName string, fn func(Interface) ([]T, error)) ([]T, error) {
+	start := time.Now()
+	for _, enabledAgent := range agents.getEnabledAgentNames() {
+		ag := agents.getAgent(enabledAgent)
+		if ag == nil {
+			continue
+		}
+		if utils.IsCtxDone(ctx) {
+			break
+		}
+		results, err := fn(ag)
+		if err != nil {
+			log.Trace(ctx, "Agent method call error", "method", methodName, "agent", ag.AgentName(), "error", err)
+			continue
+		}
+
+		if len(results) > 0 {
+			log.Debug(ctx, "Got results", "method", methodName, "agent", ag.AgentName(), "count", len(results), "elapsed", time.Since(start))
+			return results, nil
 		}
 	}
 	return nil, ErrNotFound
@@ -376,3 +377,6 @@ var _ ArtistImageRetriever = (*Agents)(nil)
 var _ ArtistTopSongsRetriever = (*Agents)(nil)
 var _ AlbumInfoRetriever = (*Agents)(nil)
 var _ AlbumImageRetriever = (*Agents)(nil)
+var _ SimilarSongsByTrackRetriever = (*Agents)(nil)
+var _ SimilarSongsByAlbumRetriever = (*Agents)(nil)
+var _ SimilarSongsByArtistRetriever = (*Agents)(nil)

core/agents/agents_test.go

@@ -295,6 +295,72 @@ var _ = Describe("Agents", func() {
 				Expect(mock.Args).To(BeEmpty())
 			})
 		})
+
+		Describe("GetSimilarSongsByTrack", func() {
+			It("returns on first match", func() {
+				Expect(ag.GetSimilarSongsByTrack(ctx, "123", "test song", "test artist", "mb123", 2)).To(Equal([]Song{{
+					Name: "Similar Song",
+					MBID: "mbid555",
+				}}))
+				Expect(mock.Args).To(HaveExactElements("123", "test song", "test artist", "mb123", 2))
+			})
+			It("skips the agent if it returns an error", func() {
+				mock.Err = errors.New("error")
+				_, err := ag.GetSimilarSongsByTrack(ctx, "123", "test song", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(HaveExactElements("123", "test song", "test artist", "mb123", 2))
+			})
+			It("interrupts if the context is canceled", func() {
+				cancel()
+				_, err := ag.GetSimilarSongsByTrack(ctx, "123", "test song", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(BeEmpty())
+			})
+		})
+
+		Describe("GetSimilarSongsByAlbum", func() {
+			It("returns on first match", func() {
+				Expect(ag.GetSimilarSongsByAlbum(ctx, "123", "test album", "test artist", "mb123", 2)).To(Equal([]Song{{
+					Name: "Album Similar Song",
+					MBID: "mbid666",
+				}}))
+				Expect(mock.Args).To(HaveExactElements("123", "test album", "test artist", "mb123", 2))
+			})
+			It("skips the agent if it returns an error", func() {
+				mock.Err = errors.New("error")
+				_, err := ag.GetSimilarSongsByAlbum(ctx, "123", "test album", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(HaveExactElements("123", "test album", "test artist", "mb123", 2))
+			})
+			It("interrupts if the context is canceled", func() {
+				cancel()
+				_, err := ag.GetSimilarSongsByAlbum(ctx, "123", "test album", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(BeEmpty())
+			})
+		})
+
+		Describe("GetSimilarSongsByArtist", func() {
+			It("returns on first match", func() {
+				Expect(ag.GetSimilarSongsByArtist(ctx, "123", "test artist", "mb123", 2)).To(Equal([]Song{{
+					Name: "Artist Similar Song",
+					MBID: "mbid777",
+				}}))
+				Expect(mock.Args).To(HaveExactElements("123", "test artist", "mb123", 2))
+			})
+			It("skips the agent if it returns an error", func() {
+				mock.Err = errors.New("error")
+				_, err := ag.GetSimilarSongsByArtist(ctx, "123", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(HaveExactElements("123", "test artist", "mb123", 2))
+			})
+			It("interrupts if the context is canceled", func() {
+				cancel()
+				_, err := ag.GetSimilarSongsByArtist(ctx, "123", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(BeEmpty())
+			})
+		})
 	})
 })
 
@@ -377,6 +443,39 @@ func (a *mockAgent) GetAlbumInfo(ctx context.Context, name, artist, mbid string)
 	}, nil
 }
 
+func (a *mockAgent) GetSimilarSongsByTrack(_ context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
+	a.Args = []interface{}{id, name, artist, mbid, count}
+	if a.Err != nil {
+		return nil, a.Err
+	}
+	return []Song{{
+		Name: "Similar Song",
+		MBID: "mbid555",
+	}}, nil
+}
+
+func (a *mockAgent) GetSimilarSongsByAlbum(_ context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
+	a.Args = []interface{}{id, name, artist, mbid, count}
+	if a.Err != nil {
+		return nil, a.Err
+	}
+	return []Song{{
+		Name: "Album Similar Song",
+		MBID: "mbid666",
+	}}, nil
+}
+
+func (a *mockAgent) GetSimilarSongsByArtist(_ context.Context, id, name, mbid string, count int) ([]Song, error) {
+	a.Args = []interface{}{id, name, mbid, count}
+	if a.Err != nil {
+		return nil, a.Err
+	}
+	return []Song{{
+		Name: "Artist Similar Song",
+		MBID: "mbid777",
+	}}, nil
+}
+
 type emptyAgent struct {
 	Interface
 }

core/agents/interfaces.go

@@ -33,9 +33,13 @@ type ExternalImage struct {
 }
 
 type Song struct {
-	ID   string
-	Name string
-	MBID string
+	ID         string
+	Name       string
+	MBID       string
+	Artist     string
+	ArtistMBID string
+	Album      string
+	AlbumMBID  string
 }
 
 var (
@@ -76,6 +80,41 @@ type ArtistTopSongsRetriever interface {
 	GetArtistTopSongs(ctx context.Context, id, artistName, mbid string, count int) ([]Song, error)
 }
 
+// SimilarSongsByTrackRetriever provides similar songs based on a specific track
+type SimilarSongsByTrackRetriever interface {
+	// GetSimilarSongsByTrack returns songs similar to the given track.
+	// Parameters:
+	//   - id: local mediafile ID
+	//   - name: track title
+	//   - artist: artist name
+	//   - mbid: MusicBrainz recording ID (may be empty)
+	//   - count: maximum number of results
+	GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error)
+}
+
+// SimilarSongsByAlbumRetriever provides similar songs based on an album
+type SimilarSongsByAlbumRetriever interface {
+	// GetSimilarSongsByAlbum returns songs similar to tracks on the given album.
+	// Parameters:
+	//   - id: local album ID
+	//   - name: album name
+	//   - artist: album artist name
+	//   - mbid: MusicBrainz release ID (may be empty)
+	//   - count: maximum number of results
+	GetSimilarSongsByAlbum(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error)
+}
+
+// SimilarSongsByArtistRetriever provides similar songs based on an artist
+type SimilarSongsByArtistRetriever interface {
+	// GetSimilarSongsByArtist returns songs similar to the artist's catalog.
+	// Parameters:
+	//   - id: local artist ID
+	//   - name: artist name
+	//   - mbid: MusicBrainz artist ID (may be empty)
+	//   - count: maximum number of results
+	GetSimilarSongsByArtist(ctx context.Context, id, name, mbid string, count int) ([]Song, error)
+}
+
 var Map map[string]Constructor
 
 func Register(name string, init Constructor) {

core/external/extdata_helper_test.go

@@ -282,3 +282,27 @@ func (m *mockAgents) GetAlbumImages(ctx context.Context, name, artist, mbid stri
 	}
 	return nil, args.Error(1)
 }
+
+func (m *mockAgents) GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]agents.Song, error) {
+	args := m.Called(ctx, id, name, artist, mbid, count)
+	if args.Get(0) != nil {
+		return args.Get(0).([]agents.Song), args.Error(1)
+	}
+	return nil, args.Error(1)
+}
+
+func (m *mockAgents) GetSimilarSongsByAlbum(ctx context.Context, id, name, artist, mbid string, count int) ([]agents.Song, error) {
+	args := m.Called(ctx, id, name, artist, mbid, count)
+	if args.Get(0) != nil {
+		return args.Get(0).([]agents.Song), args.Error(1)
+	}
+	return nil, args.Error(1)
+}
+
+func (m *mockAgents) GetSimilarSongsByArtist(ctx context.Context, id, name, mbid string, count int) ([]agents.Song, error) {
+	args := m.Called(ctx, id, name, mbid, count)
+	if args.Get(0) != nil {
+		return args.Get(0).([]agents.Song), args.Error(1)
+	}
+	return nil, args.Error(1)
+}

core/external/provider.go

@@ -32,7 +32,7 @@ const (
 type Provider interface {
 	UpdateAlbumInfo(ctx context.Context, id string) (*model.Album, error)
 	UpdateArtistInfo(ctx context.Context, id string, count int, includeNotPresent bool) (*model.Artist, error)
-	ArtistRadio(ctx context.Context, id string, count int) (model.MediaFiles, error)
+	SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error)
 	TopSongs(ctx context.Context, artist string, count int) (model.MediaFiles, error)
 	ArtistImage(ctx context.Context, id string) (*url.URL, error)
 	AlbumImage(ctx context.Context, id string) (*url.URL, error)
@@ -80,6 +80,9 @@ type Agents interface {
 	agents.ArtistSimilarRetriever
 	agents.ArtistTopSongsRetriever
 	agents.ArtistURLRetriever
+	agents.SimilarSongsByTrackRetriever
+	agents.SimilarSongsByAlbumRetriever
+	agents.SimilarSongsByArtistRetriever
 }
 
 func NewProvider(ds model.DataStore, agents Agents) Provider {
@@ -256,7 +259,7 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 	g.Go(func() error { e.callGetImage(ctx, e.ag, &artist); return nil })
 	g.Go(func() error { e.callGetBiography(ctx, e.ag, &artist); return nil })
 	g.Go(func() error { e.callGetURL(ctx, e.ag, &artist); return nil })
-	g.Go(func() error { e.callGetSimilar(ctx, e.ag, &artist, maxSimilarArtists, true); return nil })
+	g.Go(func() error { e.callGetSimilarArtists(ctx, e.ag, &artist, maxSimilarArtists, true); return nil })
 	_ = g.Wait()
 
 	if utils.IsCtxDone(ctx) {
@@ -275,22 +278,51 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 	return artist, nil
 }
 
-func (e *provider) ArtistRadio(ctx context.Context, id string, count int) (model.MediaFiles, error) {
+func (e *provider) SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error) {
+	entity, err := model.GetEntityByID(ctx, e.ds, id)
+	if err != nil {
+		return nil, err
+	}
+
+	var songs []agents.Song
+
+	// Try entity-specific similarity first
+	switch v := entity.(type) {
+	case *model.MediaFile:
+		songs, err = e.ag.GetSimilarSongsByTrack(ctx, v.ID, v.Title, v.Artist, v.MbzRecordingID, count)
+	case *model.Album:
+		songs, err = e.ag.GetSimilarSongsByAlbum(ctx, v.ID, v.Name, v.AlbumArtist, v.MbzAlbumID, count)
+	case *model.Artist:
+		songs, err = e.ag.GetSimilarSongsByArtist(ctx, v.ID, v.Name, v.MbzArtistID, count)
+	}
+
+	if err == nil && len(songs) > 0 {
+		return e.matchSongsToLibrary(ctx, songs, count)
+	}
+
+	// Fallback to existing similar artists + top songs algorithm
+	return e.similarSongsFallback(ctx, id, count)
+}
+
+// similarSongsFallback uses the original similar artists + top songs algorithm. The idea is to
+// get the artist of the given entity, retrieve similar artists, get their top songs, and pick
+// a weighted random selection of songs to return as similar songs.
+func (e *provider) similarSongsFallback(ctx context.Context, id string, count int) (model.MediaFiles, error) {
 	artist, err := e.getArtist(ctx, id)
 	if err != nil {
 		return nil, err
 	}
 
-	e.callGetSimilar(ctx, e.ag, &artist, 15, false)
+	e.callGetSimilarArtists(ctx, e.ag, &artist, 15, false)
 	if utils.IsCtxDone(ctx) {
-		log.Warn(ctx, "ArtistRadio call canceled", ctx.Err())
+		log.Warn(ctx, "SimilarSongs call canceled", ctx.Err())
 		return nil, ctx.Err()
 	}
 
 	weightedSongs := random.NewWeightedChooser[model.MediaFile]()
 	addArtist := func(a model.Artist, weightedSongs *random.WeightedChooser[model.MediaFile], count, artistWeight int) error {
 		if utils.IsCtxDone(ctx) {
-			log.Warn(ctx, "ArtistRadio call canceled", ctx.Err())
+			log.Warn(ctx, "SimilarSongs call canceled", ctx.Err())
 			return ctx.Err()
 		}
 
@@ -422,21 +454,20 @@ func (e *provider) getMatchingTopSongs(ctx context.Context, agent agents.ArtistT
 		return nil, fmt.Errorf("failed to get top songs for artist %s: %w", artistName, err)
 	}
 
-	idMatches, err := e.loadTracksByID(ctx, songs)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by ID: %w", err)
-	}
-	mbidMatches, err := e.loadTracksByMBID(ctx, songs)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by MBID: %w", err)
-	}
-	titleMatches, err := e.loadTracksByTitle(ctx, songs, artist, idMatches, mbidMatches)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by title: %w", err)
+	// Enrich songs with artist info if not already present (for top songs, we know the artist)
+	for i := range songs {
+		if songs[i].Artist == "" {
+			songs[i].Artist = artistName
+		}
+		if songs[i].ArtistMBID == "" {
+			songs[i].ArtistMBID = artist.MbzArtistID
+		}
 	}
 
-	log.Trace(ctx, "Top Songs loaded", "name", artistName, "numSongs", len(songs), "numIDMatches", len(idMatches), "numMBIDMatches", len(mbidMatches), "numTitleMatches", len(titleMatches))
-	mfs := e.selectTopSongs(songs, idMatches, mbidMatches, titleMatches, count)
+	mfs, err := e.matchSongsToLibrary(ctx, songs, count)
+	if err != nil {
+		return nil, err
+	}
 
 	if len(mfs) == 0 {
 		log.Debug(ctx, "No matching top songs found", "name", artistName)
@@ -447,137 +478,6 @@ func (e *provider) getMatchingTopSongs(ctx context.Context, agent agents.ArtistT
 	return mfs, nil
 }
 
-func (e *provider) loadTracksByMBID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
-	var mbids []string
-	for _, s := range songs {
-		if s.MBID != "" {
-			mbids = append(mbids, s.MBID)
-		}
-	}
-	matches := map[string]model.MediaFile{}
-	if len(mbids) == 0 {
-		return matches, nil
-	}
-	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
-		Filters: squirrel.And{
-			squirrel.Eq{"mbz_recording_id": mbids},
-			squirrel.Eq{"missing": false},
-		},
-	})
-	if err != nil {
-		return matches, err
-	}
-	for _, mf := range res {
-		if id := mf.MbzRecordingID; id != "" {
-			if _, ok := matches[id]; !ok {
-				matches[id] = mf
-			}
-		}
-	}
-	return matches, nil
-}
-
-func (e *provider) loadTracksByID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
-	var ids []string
-	for _, s := range songs {
-		if s.ID != "" {
-			ids = append(ids, s.ID)
-		}
-	}
-	matches := map[string]model.MediaFile{}
-	if len(ids) == 0 {
-		return matches, nil
-	}
-	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
-		Filters: squirrel.And{
-			squirrel.Eq{"media_file.id": ids},
-			squirrel.Eq{"missing": false},
-		},
-	})
-	if err != nil {
-		return matches, err
-	}
-	for _, mf := range res {
-		if _, ok := matches[mf.ID]; !ok {
-			matches[mf.ID] = mf
-		}
-	}
-	return matches, nil
-}
-
-func (e *provider) loadTracksByTitle(ctx context.Context, songs []agents.Song, artist *auxArtist, idMatches, mbidMatches map[string]model.MediaFile) (map[string]model.MediaFile, error) {
-	titleMap := map[string]string{}
-	for _, s := range songs {
-		// Skip if already matched by ID or MBID
-		if s.ID != "" && idMatches[s.ID].ID != "" {
-			continue
-		}
-		if s.MBID != "" && mbidMatches[s.MBID].ID != "" {
-			continue
-		}
-		sanitized := str.SanitizeFieldForSorting(s.Name)
-		titleMap[sanitized] = s.Name
-	}
-	matches := map[string]model.MediaFile{}
-	if len(titleMap) == 0 {
-		return matches, nil
-	}
-	titleFilters := squirrel.Or{}
-	for sanitized := range titleMap {
-		titleFilters = append(titleFilters, squirrel.Like{"order_title": sanitized})
-	}
-
-	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
-		Filters: squirrel.And{
-			squirrel.Or{
-				squirrel.Eq{"artist_id": artist.ID},
-				squirrel.Eq{"album_artist_id": artist.ID},
-			},
-			titleFilters,
-			squirrel.Eq{"missing": false},
-		},
-		Sort: "starred desc, rating desc, year asc, compilation asc ",
-	})
-	if err != nil {
-		return matches, err
-	}
-	for _, mf := range res {
-		sanitized := str.SanitizeFieldForSorting(mf.Title)
-		if _, ok := matches[sanitized]; !ok {
-			matches[sanitized] = mf
-		}
-	}
-	return matches, nil
-}
-
-func (e *provider) selectTopSongs(songs []agents.Song, byID, byMBID, byTitle map[string]model.MediaFile, count int) model.MediaFiles {
-	var mfs model.MediaFiles
-	for _, t := range songs {
-		if len(mfs) == count {
-			break
-		}
-		// Try ID match first
-		if t.ID != "" {
-			if mf, ok := byID[t.ID]; ok {
-				mfs = append(mfs, mf)
-				continue
-			}
-		}
-		// Try MBID match second
-		if t.MBID != "" {
-			if mf, ok := byMBID[t.MBID]; ok {
-				mfs = append(mfs, mf)
-				continue
-			}
-		}
-		// Fall back to title match
-		if mf, ok := byTitle[str.SanitizeFieldForSorting(t.Name)]; ok {
-			mfs = append(mfs, mf)
-		}
-	}
-	return mfs
-}
-
 func (e *provider) callGetURL(ctx context.Context, agent agents.ArtistURLRetriever, artist *auxArtist) {
 	artisURL, err := agent.GetArtistURL(ctx, artist.ID, artist.Name(), artist.MbzArtistID)
 	if err != nil {
@@ -614,7 +514,7 @@ func (e *provider) callGetImage(ctx context.Context, agent agents.ArtistImageRet
 	}
 }
 
-func (e *provider) callGetSimilar(ctx context.Context, agent agents.ArtistSimilarRetriever, artist *auxArtist,
+func (e *provider) callGetSimilarArtists(ctx context.Context, agent agents.ArtistSimilarRetriever, artist *auxArtist,
 	limit int, includeNotPresent bool) {
 	artistName := artist.Name()
 	similar, err := agent.GetSimilarArtists(ctx, artist.ID, artistName, artist.MbzArtistID, limit)

core/external/provider_artistradio_test.go

@@ -1,205 +0,0 @@
-package external_test
-
-import (
-	"context"
-	"errors"
-
-	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/core/agents"
-	. "github.com/navidrome/navidrome/core/external"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/tests"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-	"github.com/stretchr/testify/mock"
-)
-
-var _ = Describe("Provider - ArtistRadio", func() {
-	var ds model.DataStore
-	var provider Provider
-	var mockAgent *mockSimilarArtistAgent
-	var mockTopAgent agents.ArtistTopSongsRetriever
-	var mockSimilarAgent agents.ArtistSimilarRetriever
-	var agentsCombined Agents
-	var artistRepo *mockArtistRepo
-	var mediaFileRepo *mockMediaFileRepo
-	var ctx context.Context
-
-	BeforeEach(func() {
-		ctx = GinkgoT().Context()
-
-		artistRepo = newMockArtistRepo()
-		mediaFileRepo = newMockMediaFileRepo()
-
-		ds = &tests.MockDataStore{
-			MockedArtist:    artistRepo,
-			MockedMediaFile: mediaFileRepo,
-		}
-
-		mockAgent = &mockSimilarArtistAgent{}
-		mockTopAgent = mockAgent
-		mockSimilarAgent = mockAgent
-
-		agentsCombined = &mockAgents{
-			topSongsAgent: mockTopAgent,
-			similarAgent:  mockSimilarAgent,
-		}
-
-		provider = NewProvider(ds, agentsCombined)
-	})
-
-	It("returns similar songs from main artist and similar artists", func() {
-		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
-		similarArtist := model.Artist{ID: "artist-3", Name: "Similar Artist"}
-		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
-		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-2"}
-		song3 := model.MediaFile{ID: "song-3", Title: "Song Three", ArtistID: "artist-3", MbzRecordingID: "mbid-3"}
-
-		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
-		artistRepo.On("Get", "artist-3").Return(&similarArtist, nil).Maybe()
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{artist1}, nil).Once()
-
-		similarAgentsResp := []agents.Artist{
-			{Name: "Similar Artist", MBID: "similar-mbid"},
-		}
-		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
-			Return(similarAgentsResp, nil).Once()
-
-		// Mock the three-phase artist lookup: ID (skipped - no IDs), MBID, then Name
-		// MBID lookup returns empty (no match)
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			_, ok := opt.Filters.(squirrel.Eq)
-			return opt.Max == 0 && ok
-		})).Return(model.Artists{}, nil).Once()
-		// Name lookup returns the similar artist
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			_, ok := opt.Filters.(squirrel.Or)
-			return opt.Max == 0 && ok
-		})).Return(model.Artists{similarArtist}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
-			Return([]agents.Song{
-				{Name: "Song One", MBID: "mbid-1"},
-				{Name: "Song Two", MBID: "mbid-2"},
-			}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-3", "Similar Artist", "", mock.Anything).
-			Return([]agents.Song{
-				{Name: "Song Three", MBID: "mbid-3"},
-			}, nil).Once()
-
-		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
-		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song3}, nil).Once()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-1", 3)
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(songs).To(HaveLen(3))
-		for _, song := range songs {
-			Expect(song.ID).To(BeElementOf("song-1", "song-2", "song-3"))
-		}
-	})
-
-	It("returns ErrNotFound when artist is not found", func() {
-		artistRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
-		mediaFileRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{}, nil).Maybe()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-unknown-artist", 5)
-
-		Expect(err).To(Equal(model.ErrNotFound))
-		Expect(songs).To(BeNil())
-	})
-
-	It("returns songs from main artist when GetSimilarArtists returns error", func() {
-		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
-		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
-
-		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{artist1}, nil).Maybe()
-
-		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
-			Return(nil, errors.New("error getting similar artists")).Once()
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 0 && opt.Filters != nil
-		})).Return(model.Artists{}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
-			Return([]agents.Song{
-				{Name: "Song One", MBID: "mbid-1"},
-			}, nil).Once()
-
-		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-1", 5)
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(songs).To(HaveLen(1))
-		Expect(songs[0].ID).To(Equal("song-1"))
-	})
-
-	It("returns empty list when GetArtistTopSongs returns error", func() {
-		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
-
-		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{artist1}, nil).Maybe()
-
-		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
-			Return([]agents.Artist{}, nil).Once()
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 0 && opt.Filters != nil
-		})).Return(model.Artists{}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
-			Return(nil, errors.New("error getting top songs")).Once()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-1", 5)
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(songs).To(BeEmpty())
-	})
-
-	It("respects count parameter", func() {
-		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
-		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
-		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-2"}
-
-		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{artist1}, nil).Maybe()
-
-		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
-			Return([]agents.Artist{}, nil).Once()
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 0 && opt.Filters != nil
-		})).Return(model.Artists{}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
-			Return([]agents.Song{
-				{Name: "Song One", MBID: "mbid-1"},
-				{Name: "Song Two", MBID: "mbid-2"},
-			}, nil).Once()
-
-		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-1", 1)
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(songs).To(HaveLen(1))
-		Expect(songs[0].ID).To(BeElementOf("song-1", "song-2"))
-	})
-})

core/external/provider_matching.go

@@ -0,0 +1,304 @@
+package external
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/str"
+)
+
+// matchSongsToLibrary matches agent song results to local library tracks
+func (e *provider) matchSongsToLibrary(ctx context.Context, songs []agents.Song, count int) (model.MediaFiles, error) {
+	idMatches, err := e.loadTracksByID(ctx, songs)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load tracks by ID: %w", err)
+	}
+	mbidMatches, err := e.loadTracksByMBID(ctx, songs)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load tracks by MBID: %w", err)
+	}
+	titleMatches, err := e.loadTracksByTitleAndArtist(ctx, songs, idMatches, mbidMatches)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load tracks by title: %w", err)
+	}
+
+	return e.selectBestMatchingSongs(songs, idMatches, mbidMatches, titleMatches, count), nil
+}
+
+func (e *provider) loadTracksByID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
+	var ids []string
+	for _, s := range songs {
+		if s.ID != "" {
+			ids = append(ids, s.ID)
+		}
+	}
+	matches := map[string]model.MediaFile{}
+	if len(ids) == 0 {
+		return matches, nil
+	}
+	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.And{
+			squirrel.Eq{"media_file.id": ids},
+			squirrel.Eq{"missing": false},
+		},
+	})
+	if err != nil {
+		return matches, err
+	}
+	for _, mf := range res {
+		if _, ok := matches[mf.ID]; !ok {
+			matches[mf.ID] = mf
+		}
+	}
+	return matches, nil
+}
+
+func (e *provider) loadTracksByMBID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
+	var mbids []string
+	for _, s := range songs {
+		if s.MBID != "" {
+			mbids = append(mbids, s.MBID)
+		}
+	}
+	matches := map[string]model.MediaFile{}
+	if len(mbids) == 0 {
+		return matches, nil
+	}
+	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.And{
+			squirrel.Eq{"mbz_recording_id": mbids},
+			squirrel.Eq{"missing": false},
+		},
+	})
+	if err != nil {
+		return matches, err
+	}
+	for _, mf := range res {
+		if id := mf.MbzRecordingID; id != "" {
+			if _, ok := matches[id]; !ok {
+				matches[id] = mf
+			}
+		}
+	}
+	return matches, nil
+}
+
+type songQuery struct {
+	title      string
+	artist     string
+	artistMBID string
+	album      string
+	albumMBID  string
+}
+
+// loadTracksByTitleAndArtist loads tracks matching by title with optional artist/album filtering.
+// Uses per-song artist/album info when available for more precise matching.
+// Returns a map keyed by sanitized title for compatibility with selectBestMatchingSongs.
+func (e *provider) loadTracksByTitleAndArtist(ctx context.Context, songs []agents.Song, idMatches, mbidMatches map[string]model.MediaFile) (map[string]model.MediaFile, error) {
+	queries := e.buildTitleQueries(songs, idMatches, mbidMatches)
+	matches := map[string]model.MediaFile{}
+	if len(queries) == 0 {
+		return matches, nil
+	}
+
+	res, err := e.queryTracksByTitles(ctx, queries)
+	if err != nil {
+		return matches, err
+	}
+
+	indices := e.indexTracksByKeys(res)
+	return e.matchQueriesAgainstIndices(queries, indices), nil
+}
+
+func (e *provider) buildTitleQueries(songs []agents.Song, idMatches, mbidMatches map[string]model.MediaFile) []songQuery {
+	var queries []songQuery
+	for _, s := range songs {
+		// Skip if already matched by ID or MBID
+		if s.ID != "" && idMatches[s.ID].ID != "" {
+			continue
+		}
+		if s.MBID != "" && mbidMatches[s.MBID].ID != "" {
+			continue
+		}
+		queries = append(queries, songQuery{
+			title:      str.SanitizeFieldForSorting(s.Name),
+			artist:     str.SanitizeFieldForSorting(s.Artist),
+			artistMBID: s.ArtistMBID,
+			album:      str.SanitizeFieldForSorting(s.Album),
+			albumMBID:  s.AlbumMBID,
+		})
+	}
+	return queries
+}
+
+func (e *provider) queryTracksByTitles(ctx context.Context, queries []songQuery) (model.MediaFiles, error) {
+	titleSet := map[string]struct{}{}
+	for _, q := range queries {
+		titleSet[q.title] = struct{}{}
+	}
+
+	titleFilters := squirrel.Or{}
+	for title := range titleSet {
+		titleFilters = append(titleFilters, squirrel.Like{"order_title": title})
+	}
+
+	return e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.And{
+			titleFilters,
+			squirrel.Eq{"missing": false},
+		},
+		Sort: "starred desc, rating desc, year asc, compilation asc",
+	})
+}
+
+type trackIndices struct {
+	byTitleArtistMBIDAlbumMBID map[string]model.MediaFile
+	byTitleArtistMBIDAlbum     map[string]model.MediaFile
+	byTitleArtistAlbum         map[string]model.MediaFile
+	byTitleArtistMBID          map[string]model.MediaFile
+	byTitleArtist              map[string]model.MediaFile
+	byTitle                    map[string]model.MediaFile
+}
+
+func (e *provider) indexTracksByKeys(tracks model.MediaFiles) *trackIndices {
+	indices := &trackIndices{
+		byTitleArtistMBIDAlbumMBID: map[string]model.MediaFile{},
+		byTitleArtistMBIDAlbum:     map[string]model.MediaFile{},
+		byTitleArtistAlbum:         map[string]model.MediaFile{},
+		byTitleArtistMBID:          map[string]model.MediaFile{},
+		byTitleArtist:              map[string]model.MediaFile{},
+		byTitle:                    map[string]model.MediaFile{},
+	}
+
+	for _, mf := range tracks {
+		title := str.SanitizeFieldForSorting(mf.Title)
+		artist := str.SanitizeFieldForSorting(mf.Artist)
+		album := str.SanitizeFieldForSorting(mf.Album)
+		artistMBID := mf.MbzArtistID
+		albumMBID := mf.MbzAlbumID
+
+		e.indexTrackBySpecificity(indices, title, artist, album, artistMBID, albumMBID, mf)
+	}
+	return indices
+}
+
+func (e *provider) indexTrackBySpecificity(indices *trackIndices, title, artist, album, artistMBID, albumMBID string, mf model.MediaFile) {
+	addIfNotExists := func(m map[string]model.MediaFile, key string) {
+		if _, ok := m[key]; !ok {
+			m[key] = mf
+		}
+	}
+
+	if artistMBID != "" && albumMBID != "" {
+		addIfNotExists(indices.byTitleArtistMBIDAlbumMBID, title+"|"+artistMBID+"|"+albumMBID)
+	}
+	if artistMBID != "" && album != "" {
+		addIfNotExists(indices.byTitleArtistMBIDAlbum, title+"|"+artistMBID+"|"+album)
+	}
+	if artist != "" && album != "" {
+		addIfNotExists(indices.byTitleArtistAlbum, title+"|"+artist+"|"+album)
+	}
+	if artistMBID != "" {
+		addIfNotExists(indices.byTitleArtistMBID, title+"|"+artistMBID)
+	}
+	if artist != "" {
+		addIfNotExists(indices.byTitleArtist, title+"|"+artist)
+	}
+	addIfNotExists(indices.byTitle, title)
+}
+
+func (e *provider) matchQueriesAgainstIndices(queries []songQuery, indices *trackIndices) map[string]model.MediaFile {
+	matches := map[string]model.MediaFile{}
+
+	for _, q := range queries {
+		if mf, found := e.findBestMatch(q, indices); found {
+			if _, ok := matches[q.title]; !ok {
+				matches[q.title] = mf
+			}
+		}
+	}
+	return matches
+}
+
+func (e *provider) findBestMatch(q songQuery, indices *trackIndices) (model.MediaFile, bool) {
+	// Try most specific matches first
+	lookupFuncs := []func() (model.MediaFile, bool){
+		func() (model.MediaFile, bool) {
+			if q.artistMBID != "" && q.albumMBID != "" {
+				mf, ok := indices.byTitleArtistMBIDAlbumMBID[q.title+"|"+q.artistMBID+"|"+q.albumMBID]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			if q.artistMBID != "" && q.album != "" {
+				mf, ok := indices.byTitleArtistMBIDAlbum[q.title+"|"+q.artistMBID+"|"+q.album]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			if q.artist != "" && q.album != "" {
+				mf, ok := indices.byTitleArtistAlbum[q.title+"|"+q.artist+"|"+q.album]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			if q.artistMBID != "" {
+				mf, ok := indices.byTitleArtistMBID[q.title+"|"+q.artistMBID]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			if q.artist != "" {
+				mf, ok := indices.byTitleArtist[q.title+"|"+q.artist]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			mf, ok := indices.byTitle[q.title]
+			return mf, ok
+		},
+	}
+
+	for _, lookup := range lookupFuncs {
+		if mf, found := lookup(); found {
+			return mf, true
+		}
+	}
+	return model.MediaFile{}, false
+}
+
+func (e *provider) selectBestMatchingSongs(songs []agents.Song, byID, byMBID, byTitle map[string]model.MediaFile, count int) model.MediaFiles {
+	var mfs model.MediaFiles
+	for _, t := range songs {
+		if len(mfs) == count {
+			break
+		}
+		// Try ID match first
+		if t.ID != "" {
+			if mf, ok := byID[t.ID]; ok {
+				mfs = append(mfs, mf)
+				continue
+			}
+		}
+		// Try MBID match second
+		if t.MBID != "" {
+			if mf, ok := byMBID[t.MBID]; ok {
+				mfs = append(mfs, mf)
+				continue
+			}
+		}
+		// Fall back to title match
+		if mf, ok := byTitle[str.SanitizeFieldForSorting(t.Name)]; ok {
+			mfs = append(mfs, mf)
+		}
+	}
+	return mfs
+}

core/external/provider_matching_test.go

@@ -0,0 +1,324 @@
+package external_test
+
+import (
+	"context"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core/agents"
+	. "github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/stretchr/testify/mock"
+)
+
+var _ = Describe("Provider - Song Matching", func() {
+	var ds model.DataStore
+	var provider Provider
+	var agentsCombined *mockAgents
+	var artistRepo *mockArtistRepo
+	var mediaFileRepo *mockMediaFileRepo
+	var albumRepo *mockAlbumRepo
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+
+		artistRepo = newMockArtistRepo()
+		mediaFileRepo = newMockMediaFileRepo()
+		albumRepo = newMockAlbumRepo()
+
+		ds = &tests.MockDataStore{
+			MockedArtist:    artistRepo,
+			MockedMediaFile: mediaFileRepo,
+			MockedAlbum:     albumRepo,
+		}
+
+		agentsCombined = &mockAgents{}
+		provider = NewProvider(ds, agentsCombined)
+	})
+
+	Describe("matchSongsToLibrary priority matching", func() {
+		var track model.MediaFile
+
+		BeforeEach(func() {
+			track = model.MediaFile{ID: "track-1", Title: "Test Track", Artist: "Test Artist", MbzRecordingID: ""}
+
+			// Setup for GetEntityByID to return the track
+			artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+			albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+			mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
+		})
+
+		Context("when agent returns artist and album metadata", func() {
+			It("matches by title + artist MBID + album MBID (highest priority)", func() {
+				// Song in library with all MBIDs
+				correctMatch := model.MediaFile{
+					ID: "correct-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Violator",
+					MbzArtistID: "artist-mbid-123", MbzAlbumID: "album-mbid-456",
+				}
+				// Another song with same title but different MBIDs (should NOT match)
+				wrongMatch := model.MediaFile{
+					ID: "wrong-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Some Other Album",
+					MbzArtistID: "artist-mbid-123", MbzAlbumID: "different-album-mbid",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Similar Song", Artist: "Depeche Mode", ArtistMBID: "artist-mbid-123", Album: "Violator", AlbumMBID: "album-mbid-456"},
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty (no song MBID)
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns both songs
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{wrongMatch, correctMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("correct-match"))
+			})
+
+			It("matches by title + artist name + album name when MBIDs unavailable", func() {
+				// Song in library without MBIDs but with matching artist/album names
+				correctMatch := model.MediaFile{
+					ID: "correct-match", Title: "Similar Song", Artist: "depeche mode", Album: "violator",
+				}
+				// Another song with same title but different artist (should NOT match)
+				wrongMatch := model.MediaFile{
+					ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Similar Song", Artist: "Depeche Mode", Album: "Violator"}, // No MBIDs
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns both songs
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{wrongMatch, correctMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("correct-match"))
+			})
+
+			It("matches by title + artist only when album info unavailable", func() {
+				// Song in library with matching artist
+				correctMatch := model.MediaFile{
+					ID: "correct-match", Title: "Similar Song", Artist: "depeche mode", Album: "Some Album",
+				}
+				// Another song with same title but different artist
+				wrongMatch := model.MediaFile{
+					ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Similar Song", Artist: "Depeche Mode"}, // No album info
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns both songs
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{wrongMatch, correctMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("correct-match"))
+			})
+
+			It("falls back to title-only match when no artist info available", func() {
+				// Song in library
+				titleMatch := model.MediaFile{
+					ID: "title-match", Title: "Similar Song", Artist: "Random Artist",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Similar Song"}, // No artist/album info at all
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns the song
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{titleMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("title-match"))
+			})
+		})
+
+		Context("when matching multiple songs with different precision levels", func() {
+			It("prefers more precise matches for each song", func() {
+				// Library has multiple versions of same song
+				preciseMatch := model.MediaFile{
+					ID: "precise", Title: "Song A", Artist: "Artist One", Album: "Album One",
+					MbzArtistID: "mbid-1", MbzAlbumID: "album-mbid-1",
+				}
+				lessAccurateMatch := model.MediaFile{
+					ID: "less-accurate", Title: "Song A", Artist: "Artist One", Album: "Compilation",
+					MbzArtistID: "mbid-1",
+				}
+				titleOnlyMatch := model.MediaFile{
+					ID: "title-only", Title: "Song B", Artist: "Different Artist",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Song A", Artist: "Artist One", ArtistMBID: "mbid-1", Album: "Album One", AlbumMBID: "album-mbid-1"},
+						{Name: "Song B"}, // Title only
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns all candidates
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{lessAccurateMatch, preciseMatch, titleOnlyMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(2))
+				// First song should be the precise match (has all MBIDs)
+				Expect(songs[0].ID).To(Equal("precise"))
+				// Second song should be title-only match
+				Expect(songs[1].ID).To(Equal("title-only"))
+			})
+		})
+	})
+})

core/external/provider_similarsongs_test.go

@@ -0,0 +1,435 @@
+package external_test
+
+import (
+	"context"
+	"errors"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core/agents"
+	. "github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/stretchr/testify/mock"
+)
+
+var _ = Describe("Provider - SimilarSongs", func() {
+	var ds model.DataStore
+	var provider Provider
+	var mockAgent *mockSimilarArtistAgent
+	var mockTopAgent agents.ArtistTopSongsRetriever
+	var mockSimilarAgent agents.ArtistSimilarRetriever
+	var agentsCombined *mockAgents
+	var artistRepo *mockArtistRepo
+	var mediaFileRepo *mockMediaFileRepo
+	var albumRepo *mockAlbumRepo
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+
+		artistRepo = newMockArtistRepo()
+		mediaFileRepo = newMockMediaFileRepo()
+		albumRepo = newMockAlbumRepo()
+
+		ds = &tests.MockDataStore{
+			MockedArtist:    artistRepo,
+			MockedMediaFile: mediaFileRepo,
+			MockedAlbum:     albumRepo,
+		}
+
+		mockAgent = &mockSimilarArtistAgent{}
+		mockTopAgent = mockAgent
+		mockSimilarAgent = mockAgent
+
+		agentsCombined = &mockAgents{
+			topSongsAgent: mockTopAgent,
+			similarAgent:  mockSimilarAgent,
+		}
+
+		provider = NewProvider(ds, agentsCombined)
+	})
+
+	Describe("dispatch by entity type", func() {
+		Context("when ID is a MediaFile (track)", func() {
+			It("calls GetSimilarSongsByTrack and returns matched songs", func() {
+				track := model.MediaFile{ID: "track-1", Title: "Just Can't Get Enough", Artist: "Depeche Mode", MbzRecordingID: "track-mbid"}
+				matchedSong := model.MediaFile{ID: "matched-1", Title: "Dreaming of Me", Artist: "Depeche Mode"}
+
+				// GetEntityByID tries Artist, Album, Playlist, then MediaFile
+				artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Just Can't Get Enough", "Depeche Mode", "track-mbid", 5).
+					Return([]agents.Song{
+						{Name: "Dreaming of Me", MBID: "", Artist: "Depeche Mode", ArtistMBID: "artist-mbid"},
+					}, nil).Once()
+
+				// Mock loadTracksByID - no ID matches
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// Mock loadTracksByMBID - no MBID matches (empty MBID)
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					eq, ok := opt.Filters.(squirrel.And)
+					if !ok || len(eq) < 1 {
+						return false
+					}
+					_, hasEq := eq[0].(squirrel.Eq)
+					return hasEq
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// Mock loadTracksByTitleOnly - title matches
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{matchedSong}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("matched-1"))
+			})
+
+			It("falls back to artist-based algorithm when GetSimilarSongsByTrack returns empty", func() {
+				track := model.MediaFile{ID: "track-1", Title: "Track", Artist: "Artist", ArtistID: "artist-1"}
+				artist := model.Artist{ID: "artist-1", Name: "Artist"}
+				song := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+
+				// GetEntityByID for the initial call tries Artist, Album, Playlist, then MediaFile
+				artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Track", "Artist", "", mock.Anything).
+					Return([]agents.Song{}, nil).Once()
+
+				// Fallback calls getArtist(id) which calls GetEntityByID again - this time it finds the mediafile
+				// and recursively calls getArtist(v.ArtistID)
+				artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
+
+				// Then it recurses with the artist-1 ID
+				artistRepo.On("Get", "artist-1").Return(&artist, nil).Maybe()
+				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					return opt.Max == 1 && opt.Filters != nil
+				})).Return(model.Artists{artist}, nil).Maybe()
+
+				mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist", "", 15).
+					Return([]agents.Artist{}, nil).Once()
+
+				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					return opt.Max == 0 && opt.Filters != nil
+				})).Return(model.Artists{}, nil).Once()
+
+				mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist", "", mock.Anything).
+					Return([]agents.Song{{Name: "Song One", MBID: "mbid-1"}}, nil).Once()
+
+				mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("song-1"))
+			})
+		})
+
+		Context("when ID is an Album", func() {
+			It("calls GetSimilarSongsByAlbum and returns matched songs", func() {
+				album := model.Album{ID: "album-1", Name: "Speak & Spell", AlbumArtist: "Depeche Mode", MbzAlbumID: "album-mbid"}
+				matchedSong := model.MediaFile{ID: "matched-1", Title: "New Life", Artist: "Depeche Mode", MbzRecordingID: "song-mbid"}
+
+				// GetEntityByID tries Artist, Album, Playlist, then MediaFile
+				artistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "album-1").Return(&album, nil).Once()
+
+				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "album-1", "Speak & Spell", "Depeche Mode", "album-mbid", 5).
+					Return([]agents.Song{
+						{Name: "New Life", MBID: "song-mbid", Artist: "Depeche Mode"},
+					}, nil).Once()
+
+				// Mock loadTracksByID - no ID matches
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// Mock loadTracksByMBID - MBID match
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					_, hasEq := and[0].(squirrel.Eq)
+					return hasEq
+				})).Return(model.MediaFiles{matchedSong}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "album-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("matched-1"))
+			})
+
+			It("falls back when GetSimilarSongsByAlbum returns ErrNotFound", func() {
+				album := model.Album{ID: "album-1", Name: "Album", AlbumArtist: "Artist", AlbumArtistID: "artist-1"}
+				artist := model.Artist{ID: "artist-1", Name: "Artist"}
+				song := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+
+				// GetEntityByID for the initial call tries Artist, Album, Playlist, then MediaFile
+				artistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "album-1").Return(&album, nil).Once()
+
+				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "album-1", "Album", "Artist", "", mock.Anything).
+					Return(nil, agents.ErrNotFound).Once()
+
+				// Fallback calls getArtist(id) which calls GetEntityByID again - this time it finds the album
+				// and recursively calls getArtist(v.AlbumArtistID)
+				artistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "album-1").Return(&album, nil).Once()
+
+				// Then it recurses with the artist-1 ID
+				artistRepo.On("Get", "artist-1").Return(&artist, nil).Maybe()
+				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					return opt.Max == 1 && opt.Filters != nil
+				})).Return(model.Artists{artist}, nil).Maybe()
+
+				mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist", "", 15).
+					Return([]agents.Artist{}, nil).Once()
+
+				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					return opt.Max == 0 && opt.Filters != nil
+				})).Return(model.Artists{}, nil).Once()
+
+				mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist", "", mock.Anything).
+					Return([]agents.Song{{Name: "Song One", MBID: "mbid-1"}}, nil).Once()
+
+				mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "album-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("song-1"))
+			})
+		})
+
+		Context("when ID is an Artist", func() {
+			It("calls GetSimilarSongsByArtist and returns matched songs", func() {
+				artist := model.Artist{ID: "artist-1", Name: "Depeche Mode", MbzArtistID: "artist-mbid"}
+				matchedSong := model.MediaFile{ID: "matched-1", Title: "Enjoy the Silence", Artist: "Depeche Mode", MbzRecordingID: "song-mbid"}
+
+				artistRepo.On("Get", "artist-1").Return(&artist, nil).Once()
+				agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Depeche Mode", "artist-mbid", 5).
+					Return([]agents.Song{
+						{Name: "Enjoy the Silence", MBID: "song-mbid", Artist: "Depeche Mode"},
+					}, nil).Once()
+
+				// Mock loadTracksByID - no ID matches
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// Mock loadTracksByMBID - MBID match
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					_, hasEq := and[0].(squirrel.Eq)
+					return hasEq
+				})).Return(model.MediaFiles{matchedSong}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "artist-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("matched-1"))
+			})
+		})
+	})
+
+	It("returns similar songs from main artist and similar artists", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
+		similarArtist := model.Artist{ID: "artist-3", Name: "Similar Artist"}
+		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-2"}
+		song3 := model.MediaFile{ID: "song-3", Title: "Song Three", ArtistID: "artist-3", MbzRecordingID: "mbid-3"}
+
+		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
+		artistRepo.On("Get", "artist-3").Return(&similarArtist, nil).Maybe()
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{artist1}, nil).Once()
+
+		// New similar songs by artist returns ErrNotFound to trigger fallback
+		agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, agents.ErrNotFound).Once()
+
+		similarAgentsResp := []agents.Artist{
+			{Name: "Similar Artist", MBID: "similar-mbid"},
+		}
+		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
+			Return(similarAgentsResp, nil).Once()
+
+		// Mock the three-phase artist lookup: ID (skipped - no IDs), MBID, then Name
+		// MBID lookup returns empty (no match)
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			_, ok := opt.Filters.(squirrel.Eq)
+			return opt.Max == 0 && ok
+		})).Return(model.Artists{}, nil).Once()
+		// Name lookup returns the similar artist
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			_, ok := opt.Filters.(squirrel.Or)
+			return opt.Max == 0 && ok
+		})).Return(model.Artists{similarArtist}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return([]agents.Song{
+				{Name: "Song One", MBID: "mbid-1"},
+				{Name: "Song Two", MBID: "mbid-2"},
+			}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-3", "Similar Artist", "", mock.Anything).
+			Return([]agents.Song{
+				{Name: "Song Three", MBID: "mbid-3"},
+			}, nil).Once()
+
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song3}, nil).Once()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-1", 3)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(HaveLen(3))
+		for _, song := range songs {
+			Expect(song.ID).To(BeElementOf("song-1", "song-2", "song-3"))
+		}
+	})
+
+	It("returns ErrNotFound when artist is not found", func() {
+		artistRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
+		mediaFileRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
+		albumRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{}, nil).Maybe()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-unknown-artist", 5)
+
+		Expect(err).To(Equal(model.ErrNotFound))
+		Expect(songs).To(BeNil())
+	})
+
+	It("returns songs from main artist when GetSimilarArtists returns error", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
+		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+
+		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{artist1}, nil).Maybe()
+
+		// New similar songs by artist returns ErrNotFound to trigger fallback
+		agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, agents.ErrNotFound).Once()
+
+		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
+			Return(nil, errors.New("error getting similar artists")).Once()
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 0 && opt.Filters != nil
+		})).Return(model.Artists{}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return([]agents.Song{
+				{Name: "Song One", MBID: "mbid-1"},
+			}, nil).Once()
+
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-1", 5)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(HaveLen(1))
+		Expect(songs[0].ID).To(Equal("song-1"))
+	})
+
+	It("returns empty list when GetArtistTopSongs returns error", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
+
+		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{artist1}, nil).Maybe()
+
+		// New similar songs by artist returns ErrNotFound to trigger fallback
+		agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, agents.ErrNotFound).Once()
+
+		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
+			Return([]agents.Artist{}, nil).Once()
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 0 && opt.Filters != nil
+		})).Return(model.Artists{}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, errors.New("error getting top songs")).Once()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-1", 5)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(BeEmpty())
+	})
+
+	It("respects count parameter", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
+		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-2"}
+
+		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{artist1}, nil).Maybe()
+
+		// New similar songs by artist returns ErrNotFound to trigger fallback
+		agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, agents.ErrNotFound).Once()
+
+		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
+			Return([]agents.Artist{}, nil).Once()
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 0 && opt.Filters != nil
+		})).Return(model.Artists{}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return([]agents.Song{
+				{Name: "Song One", MBID: "mbid-1"},
+				{Name: "Song Two", MBID: "mbid-2"},
+			}, nil).Once()
+
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-1", 1)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(HaveLen(1))
+		Expect(songs[0].ID).To(BeElementOf("song-1", "song-2"))
+	})
+})

server/subsonic/browsing.go

@@ -354,7 +354,7 @@ func (api *Router) GetSimilarSongs(r *http.Request) (*responses.Subsonic, error)
 	}
 	count := p.IntOr("count", 50)
 
-	songs, err := api.provider.ArtistRadio(ctx, id, count)
+	songs, err := api.provider.SimilarSongs(ctx, id, count)
 	if err != nil {
 		return nil, err
 	}

tests/fixtures/lastfm.track.getsimilar.json

@@ -0,0 +1 @@
+{"similartracks":{"track":[{"name":"Dreaming of Me","mbid":"027b553e-7c74-3ed4-a95e-1d4fea51f174","match":1.0,"url":"https://www.last.fm/music/Depeche+Mode/_/Dreaming+of+Me","artist":{"name":"Depeche Mode","mbid":"8538e728-ca0b-4321-b7e5-cff6565dd4c0","url":"https://www.last.fm/music/Depeche+Mode"}},{"name":"Everything Counts","mbid":"5a5a3ca4-bdb8-4641-a674-9b54b9b319a6","match":0.892602,"url":"https://www.last.fm/music/Depeche+Mode/_/Everything+Counts","artist":{"name":"Depeche Mode","mbid":"8538e728-ca0b-4321-b7e5-cff6565dd4c0","url":"https://www.last.fm/music/Depeche+Mode"}},{"name":"Don't You Want Me","mbid":"","match":0.491341,"url":"https://www.last.fm/music/The+Human+League/_/Don%27t+You+Want+Me","artist":{"name":"The Human League","mbid":"7adaabfb-acfb-47bc-8c7c-59471c2f0db8","url":"https://www.last.fm/music/The+Human+League"}},{"name":"Tainted Love","mbid":"","match":0.454811,"url":"https://www.last.fm/music/Soft+Cell/_/Tainted+Love","artist":{"name":"Soft Cell","mbid":"7fb50287-029d-47cc-825a-235ca28024b2","url":"https://www.last.fm/music/Soft+Cell"}},{"name":"Blue Monday","mbid":"727e84c6-1b56-31dd-a958-a5f46305cec0","match":0.381057,"url":"https://www.last.fm/music/New+Order/_/Blue+Monday","artist":{"name":"New Order","mbid":"f1106b17-dcbb-45f6-b938-199ccfab50cc","url":"https://www.last.fm/music/New+Order"}}],"@attr":{"artist":"Depeche Mode","track":"Just Can't Get Enough"}}}

tests/fixtures/lastfm.track.getsimilar.unknown.json

@@ -0,0 +1 @@
+{"similartracks":{"track":[],"@attr":{"track":"UnknownTrack","artist":"UnknownArtist"}}}