feat: add ID fields to Artist and Song structs and enhance track loading logic by prioritizing ID matches

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

plugins/capabilities/metadata_agent.go

@@ -92,6 +92,8 @@ type SimilarArtistsRequest struct {
 
 // ArtistRef is a reference to an artist with name and optional MBID.
 type ArtistRef struct {
+	// ID is the internal Navidrome artist ID (if known).
+	ID string `json:"id,omitempty"`
 	// Name is the artist name.
 	Name string `json:"name"`
 	// MBID is the MusicBrainz ID for the artist.
@@ -132,6 +134,8 @@ type TopSongsRequest struct {
 
 // SongRef is a reference to a song with name and optional MBID.
 type SongRef struct {
+	// ID is the internal Navidrome mediafile ID (if known).
+	ID string `json:"id,omitempty"`
 	// Name is the song name.
 	Name string `json:"name"`
 	// MBID is the MusicBrainz ID for the song.

plugins/capabilities/metadata_agent.yaml

@@ -152,6 +152,9 @@ components:
         ArtistRef:
             description: ArtistRef is a reference to an artist with name and optional MBID.
             properties:
+                id:
+                    type: string
+                    description: ID is the internal Navidrome artist ID (if known).
                 name:
                     type: string
                     description: Name is the artist name.
@@ -229,6 +232,9 @@ components:
         SongRef:
             description: SongRef is a reference to a song with name and optional MBID.
             properties:
+                id:
+                    type: string
+                    description: ID is the internal Navidrome mediafile ID (if known).
                 name:
                     type: string
                     description: Name is the song name.

plugins/metadata_agent.go

@@ -109,7 +109,7 @@ func (a *MetadataAgent) GetSimilarArtists(ctx context.Context, id, name, mbid st
 
 	artists := make([]agents.Artist, len(result.Artists))
 	for i, ar := range result.Artists {
-		artists[i] = agents.Artist{Name: ar.Name, MBID: ar.MBID}
+		artists[i] = agents.Artist{ID: ar.ID, Name: ar.Name, MBID: ar.MBID}
 	}
 
 	return artists, nil
@@ -149,7 +149,7 @@ func (a *MetadataAgent) GetArtistTopSongs(ctx context.Context, id, artistName, m
 
 	songs := make([]agents.Song, len(result.Songs))
 	for i, s := range result.Songs {
-		songs[i] = agents.Song{Name: s.Name, MBID: s.MBID}
+		songs[i] = agents.Song{ID: s.ID, Name: s.Name, MBID: s.MBID}
 	}
 
 	return songs, nil

plugins/pdk/go/metadata/metadata.go

@@ -67,6 +67,8 @@ type ArtistMBIDResponse struct {
 
 // ArtistRef is a reference to an artist with name and optional MBID.
 type ArtistRef struct {
+	// ID is the internal Navidrome artist ID (if known).
+	ID string `json:"id,omitempty"`
 	// Name is the artist name.
 	Name string `json:"name"`
 	// MBID is the MusicBrainz ID for the artist.
@@ -117,6 +119,8 @@ type SimilarArtistsResponse struct {
 
 // SongRef is a reference to a song with name and optional MBID.
 type SongRef struct {
+	// ID is the internal Navidrome mediafile ID (if known).
+	ID string `json:"id,omitempty"`
 	// Name is the song name.
 	Name string `json:"name"`
 	// MBID is the MusicBrainz ID for the song.

plugins/pdk/go/metadata/metadata_stub.go

@@ -64,6 +64,8 @@ type ArtistMBIDResponse struct {
 
 // ArtistRef is a reference to an artist with name and optional MBID.
 type ArtistRef struct {
+	// ID is the internal Navidrome artist ID (if known).
+	ID string `json:"id,omitempty"`
 	// Name is the artist name.
 	Name string `json:"name"`
 	// MBID is the MusicBrainz ID for the artist.
@@ -114,6 +116,8 @@ type SimilarArtistsResponse struct {
 
 // SongRef is a reference to a song with name and optional MBID.
 type SongRef struct {
+	// ID is the internal Navidrome mediafile ID (if known).
+	ID string `json:"id,omitempty"`
 	// Name is the song name.
 	Name string `json:"name"`
 	// MBID is the MusicBrainz ID for the song.

plugins/pdk/rust/nd-pdk-capabilities/src/metadata.rs

@@ -82,6 +82,9 @@ pub struct ArtistMBIDResponse {
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ArtistRef {
+    /// ID is the internal Navidrome artist ID (if known).
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub id: String,
     /// Name is the artist name.
     #[serde(default)]
     pub name: String,
@@ -151,6 +154,9 @@ pub struct SimilarArtistsResponse {
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SongRef {
+    /// ID is the internal Navidrome mediafile ID (if known).
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub id: String,
     /// Name is the song name.
     #[serde(default)]
     pub name: String,

plugins/testdata/test-metadata-agent/main.go

@@ -70,7 +70,9 @@ func (t *testMetadataAgent) GetSimilarArtists(input metadata.SimilarArtistsReque
 	artists := make([]metadata.ArtistRef, 0, limit)
 	for i := range limit {
 		artists = append(artists, metadata.ArtistRef{
+			ID:   "similar-artist-id-" + strconv.Itoa(i+1),
 			Name: input.Name + " Similar " + string(rune('A'+i)),
+			MBID: "similar-mbid-" + strconv.Itoa(i+1),
 		})
 	}
 	return &metadata.SimilarArtistsResponse{Artists: artists}, nil
@@ -87,7 +89,9 @@ func (t *testMetadataAgent) GetArtistTopSongs(input metadata.TopSongsRequest) (*
 	songs := make([]metadata.SongRef, 0, count)
 	for i := range count {
 		songs = append(songs, metadata.SongRef{
+			ID:   "song-id-" + strconv.Itoa(i+1),
 			Name: input.Name + " Song " + strconv.Itoa(i+1),
+			MBID: "song-mbid-" + strconv.Itoa(i+1),
 		})
 	}
 	return &metadata.TopSongsResponse{Songs: songs}, nil