feat: add similar songs functionality in agents, and Instant Mix (song-based) to UI

[deluan]

Description

This PR implements similar songs functionality in Navidrome, allowing users to discover songs similar to a given track, album, or artist. The implementation leverages external music services (like Last.fm) to retrieve song similarity data and matches them against the user's music library.

Key Features

• Song-level similarity: Get similar songs based on a specific track with enhanced matching using title, artist, and album metadata
• Enhanced matching algorithm: Implements a multi-level matching strategy prioritizing MBID, then title+artist+album, then title+artist, and finally title-only matches
• Comprehensive test coverage: Added extensive unit tests covering all matching scenarios and edge cases
• Code quality improvements: Refactored complex functions to reduce cyclomatic complexity

New Agent Interfaces

Three new agent interfaces were added to core/agents/interfaces.go:

1. SimilarSongsByTrackRetriever - Get similar songs based on a specific track

   • GetSimilarSongsByTrack(ctx, id, name, artist, mbid, count) returns songs similar to the given track

2. SimilarSongsByAlbumRetriever - Get similar songs based on an album

   • GetSimilarSongsByAlbum(ctx, id, name, artist, mbid, count) returns songs similar to tracks on the given album

3. SimilarSongsByArtistRetriever - Get similar songs based on an artist

   • GetSimilarSongsByArtist(ctx, id, name, mbid, count) returns songs similar to the artist's catalog

Enhanced Song Struct

The agents.Song struct was extended with additional metadata fields to enable better matching:

type Song struct {
    ID         string
    Name       string
    MBID       string
    Artist     string    // NEW
    ArtistMBID string    // NEW
    Album      string    // NEW
    AlbumMBID  string    // NEW
}

Agents Implementation

The Agents meta-agent now implements all three new interfaces:

• Tries each enabled agent in order until one returns valid data
• Over-fetches results (using DevExternalArtistFetchMultiplier) since some returned songs may not exist in the local database
• Properly handles special cases (Unknown Artist, Various Artists)

Last.fm Integration

Added track.getSimilar API support to the Last.fm agent:

• New GetSimilarSongsByTrack method calls the Last.fm API
• New response types: SimilarTracks, SimilarTrack, SimilarTrackArtist, SimilarAttr
• Returns artist name and MBID along with track info for better matching

Smart Matching Algorithm

The new provider_matching.go file contains sophisticated matching logic:

1. ID matching: Direct match by local media file ID
2. MBID matching: Match by MusicBrainz recording ID
3. Title + metadata matching: Multi-level fallback:
   • Title + ArtistMBID + AlbumMBID (most specific)
   • Title + ArtistMBID + Album name
   • Title + Artist name + Album name
   • Title + ArtistMBID
   • Title + Artist name
   • Title only (least specific)

Results are sorted by: starred status, rating, year (ascending), compilation status

Refactoring

• Renamed ArtistRadio to SimilarSongs for clarity and consistency
• Extracted song matching functionality into dedicated provider_matching.go file
• Reduced cyclomatic complexity by breaking down large functions into smaller, focused helpers

Type of Change

• New feature
• Bug fix
• Documentation update
• Refactor
• Other (please describe):

Checklist

• My code follows the project's coding style
• I have tested the changes locally
• I have added or updated documentation as needed
• I have added tests that prove my fix/feature works
• All existing and new tests pass

How to Test

1. Configure Navidrome with Last.fm API credentials
2. Use the Subsonic API endpoint getSimilarSongs2 with a song ID
3. Verify that similar songs are returned and correctly matched to your library
4. Check that the matching prioritizes exact metadata matches over fuzzy matches
5. Run the test suite: make test

Files Changed

• core/agents/interfaces.go - New interfaces and extended Song struct
• core/agents/agents.go - Meta-agent implementations for new interfaces
• core/agents/agents_test.go - Tests for new agent methods
• adapters/lastfm/agent.go - Last.fm GetSimilarSongsByTrack implementation
• adapters/lastfm/client.go - Last.fm API client for track.getSimilar
• adapters/lastfm/responses.go - Response types for similar tracks
• adapters/lastfm/*_test.go - Tests for Last.fm changes
• core/external/provider.go - SimilarSongs method (renamed from ArtistRadio)
• core/external/provider_matching.go - Extracted matching logic
• core/external/provider_matching_test.go - Tests for matching logic
• core/external/provider_similarsongs_test.go - Tests for SimilarSongs
• server/subsonic/browsing.go - Updated to use renamed method
• tests/fixtures/lastfm.track.getsimilar*.json - Test fixtures

[gemini-code-assist]

Summary of Changes

Hello @deluan, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant new capability to Navidrome, allowing users to discover music similar to a specific track, album, or artist from their library. It intelligently integrates with external music services to retrieve similarity data and then applies a sophisticated, multi-criteria matching process to find corresponding songs within the user's local collection. This enhancement aims to provide a richer and more dynamic music discovery experience.

Highlights

• Similar Songs Functionality: Introduced a new feature to find similar songs based on a given track, album, or artist, leveraging external music services like Last.fm.
• Enhanced Matching Algorithm: Implemented a multi-level matching strategy to accurately link external similar song data with the user's local music library. This prioritizes matches by MusicBrainz ID (MBID), then title+artist+album, then title+artist, and finally title-only.
• Last.fm Integration: Added new methods to the Last.fm agent to fetch similar track data, including new API client calls and response structures.
• Core Agent Updates: The core Agents meta-agent now includes new retriever interfaces and methods (GetSimilarSongsByTrack, GetSimilarSongsByAlbum, GetSimilarSongsByArtist) to aggregate similar song results from various configured agents.
• Refactored External Provider: The external provider has been refactored to dispatch similar song requests based on the entity type (track, album, or artist) and includes a fallback mechanism to the existing artist-based radio algorithm if entity-specific similarity data is not found.
• Comprehensive Testing: Extensive unit tests have been added for the new Last.fm agent methods, the core Agents dispatch logic, and the complex song matching algorithm to ensure robustness and correctness.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-implemented feature for finding similar songs. The changes are well-structured, separating the Last.fm adapter logic, agent aggregation, and the new provider-level song matching logic. The hierarchical matching algorithm is a robust approach to finding songs in the user's library. The code is also accompanied by comprehensive tests. I've identified a potential logic bug in the new matching implementation and a couple of opportunities for code improvement, which are detailed in the review comments. Overall, this is an excellent contribution.

[github-actions]

Download the artifacts for this pull request:

• navidrome-darwin_arm64.zip
• navidrome-linux_arm_v7.zip
• navidrome-linux_arm_v5.zip
• navidrome-linux_386.zip
• navidrome-linux_amd64.zip
• navidrome-linux_arm_v6.zip
• navidrome-darwin_amd64.zip
• navidrome-windows_386.zip
• navidrome-linux_arm64.zip
• navidrome-windows_amd64.zip
• navidrome-windows-installers.zip
• packages.zip
• navidrome_linux_386.rpm.zip
• navidrome_linux_arm64.deb.zip
• navidrome_linux_armv6.deb.zip
• navidrome_linux_armv7.rpm.zip
• navidrome_linux_arm64.rpm.zip
• navidrome_linux_amd64.deb.zip
• navidrome_linux_armv6.rpm.zip
• navidrome_linux_armv5.deb.zip
• navidrome_linux_armv7.deb.zip
• navidrome_linux_386.deb.zip
• navidrome_linux_armv5.rpm.zip
• navidrome_linux_amd64.rpm.zip

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 977915252e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR implements a similar songs feature for Navidrome, allowing users to discover songs similar to a given track, album, or artist. The implementation leverages external music services (like Last.fm) to retrieve similarity data and matches them against the user's local library using an enhanced multi-level matching algorithm.

Changes:

• Added three new agent interfaces for track-level, album-level, and artist-level similar song retrieval
• Extended the agents.Song struct with artist and album metadata fields for improved matching accuracy
• Implemented a sophisticated matching algorithm that prioritizes matches by ID, MBID, and progressively less specific metadata combinations
• Renamed ArtistRadio to SimilarSongs for clarity and added entity-type dispatching with fallback to the existing algorithm

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
core/agents/interfaces.go	Added three new retriever interfaces and extended Song struct with artist/album metadata fields
core/agents/agents.go	Implemented meta-agent methods for new interfaces with refactored helper functions to reduce duplication
core/agents/agents_test.go	Added comprehensive test coverage for all three new similar songs methods
adapters/lastfm/agent.go	Implemented GetSimilarSongsByTrack using Last.fm's track.getSimilar API
adapters/lastfm/client.go	Added trackGetSimilar client method for Last.fm API integration
adapters/lastfm/responses.go	Added response types for similar tracks API
adapters/lastfm/client_test.go	Added tests for track.getSimilar client method
adapters/lastfm/agent_test.go	Added tests for GetSimilarSongsByTrack agent method
core/external/provider.go	Renamed ArtistRadio to SimilarSongs, added entity-type dispatching with fallback, refactored to use shared matching logic
core/external/provider_matching.go	Extracted sophisticated multi-level matching algorithm into dedicated file
core/external/provider_matching_test.go	Added comprehensive tests for matching algorithm covering all priority levels
core/external/provider_similarsongs_test.go	Added tests for SimilarSongs method covering all entity types and fallback scenarios
core/external/provider_artistradio_test.go	Removed old test file (functionality moved to provider_similarsongs_test.go)
core/external/extdata_helper_test.go	Added mock implementations for new similar songs interfaces
server/subsonic/browsing.go	Updated to call renamed SimilarSongs method
tests/fixtures/lastfm.track.getsimilar.json	Added test fixture with sample Last.fm similar tracks response
tests/fixtures/lastfm.track.getsimilar.unknown.json	Added test fixture for unknown track scenario

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.