Merge branch 'master' into users-score

.github/workflows/pipeline.yml

@@ -24,7 +24,7 @@ jobs:
       git_tag: ${{ steps.git-version.outputs.GIT_TAG }}
       git_sha: ${{ steps.git-version.outputs.GIT_SHA }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           fetch-tags: true
@@ -62,7 +62,7 @@ jobs:
     name: Lint Go code
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - uses: actions/setup-go@v6
         with:
@@ -101,7 +101,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code into the Go module directory
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - uses: actions/setup-go@v6
         with:
@@ -127,7 +127,7 @@ jobs:
       FFMPEG_VERSION: "7.1"
       FFMPEG_REPOSITORY: navidrome/ffmpeg-windows-builds
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - uses: actions/setup-go@v6
         with:
@@ -199,7 +199,7 @@ jobs:
     env:
       NODE_OPTIONS: "--max_old_space_size=4096"
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-node@v6
         with:
           node-version: 24
@@ -230,7 +230,7 @@ jobs:
     name: Lint i18n files
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - run: |
           set -e
           for file in resources/i18n/*.json; do
@@ -276,7 +276,7 @@ jobs:
           PLATFORM=$(echo ${{ matrix.platform }} | tr '/' '_')
           echo "PLATFORM=$PLATFORM" >> $GITHUB_ENV
 
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Prepare Docker Buildx
         uses: ./.github/actions/prepare-docker
@@ -350,7 +350,7 @@ jobs:
     env:
       REGISTRY_IMAGE: ghcr.io/${{ github.repository }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Download digests
         uses: actions/download-artifact@v8
@@ -384,7 +384,7 @@ jobs:
     if: needs.check-push-enabled.outputs.is_enabled == 'true' && vars.DOCKER_HUB_REPO != ''
     continue-on-error: true
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Download digests
         uses: actions/download-artifact@v8
@@ -437,7 +437,7 @@ jobs:
     runs-on: ubuntu-24.04
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - uses: actions/download-artifact@v8
         with:
@@ -471,7 +471,7 @@ jobs:
     outputs:
       package_list: ${{ steps.set-package-list.outputs.package_list }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           fetch-tags: true

.github/workflows/push-translations.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.repository_owner == 'navidrome' }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 2
 

.github/workflows/update-translations.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.repository_owner == 'navidrome' }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - name: Get updated translations
         id: poeditor
         env:

.golangci.yml

@@ -13,6 +13,7 @@ linters:
     - dogsled
     - durationcheck
     - errorlint
+    - forbidigo
     - gocritic
     - gocyclo
     - goprintffuncname
@@ -36,6 +37,14 @@ linters:
         - G401
         - G505
         - G115
+    forbidigo:
+      forbid:
+        - pattern: 'tx\.Exec$'
+          msg: "use tx.ExecContext(ctx, ...) in migrations to propagate context"
+        - pattern: 'tx\.Query$'
+          msg: "use tx.QueryContext(ctx, ...) in migrations to propagate context"
+        - pattern: 'tx\.QueryRow$'
+          msg: "use tx.QueryRowContext(ctx, ...) in migrations to propagate context"
     govet:
       enable:
         - nilness
@@ -45,6 +54,9 @@ linters:
           - gosec
         path: _test\.go
         text: "G703"
+      - path-except: 'db/migrations/'
+        linters:
+          - forbidigo
     generated: lax
     presets:
       - comments
@@ -56,6 +68,7 @@ linters:
       - builtin$
       - examples$
       - node_modules
+      - _gen\.go$
 formatters:
   exclusions:
     generated: lax

README.md

@@ -52,6 +52,7 @@ A share of the revenue helps fund the development of Navidrome at no additional
  - **Multi-platform**, runs on macOS, Linux and Windows. **Docker** images are also provided
  - Ready to use binaries for all major platforms, including **Raspberry Pi**
  - Automatically **monitors your library** for changes, importing new files and reloading new metadata 
+ - Supports **lyrics** from sidecar .ttml, .yaml/.yml Lyricsfile, .elrc, .lrc, .srt, .txt files and embedded TTML, Enhanced LRC, LRC, SRT, and plain-text tags (via `lyricspriority`)
  - **Themeable**, modern and responsive **Web interface** based on [Material UI](https://material-ui.com)
  - **Compatible** with all Subsonic/Madsonic/Airsonic [clients](https://www.navidrome.org/docs/overview/#apps)
  - **Transcoding** on the fly. Can be set per user/player. **Opus encoding is supported**

cmd/wire_gen.go

@@ -109,7 +109,7 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
 	playTracker := scrobbler.GetPlayTracker(dataStore, broker, manager)
 	playbackServer := playback.GetInstance(dataStore)
-	lyricsLyrics := lyrics.NewLyrics(manager)
+	lyricsLyrics := lyrics.NewLyrics(dataStore, manager)
 	transcodeDecider := stream.NewTranscodeDecider(dataStore, fFmpeg)
 	sonicSonic := sonic.New(dataStore, manager, matcherMatcher)
 	router := subsonic.New(dataStore, artworkArtwork, mediaStreamer, archiver, players, provider, modelScanner, broker, playlistsPlaylists, playTracker, share, playbackServer, metricsMetrics, lyricsLyrics, transcodeDecider, sonicSonic)

conf/configuration.go

@@ -162,6 +162,7 @@ type scannerOptions struct {
 	GenreSeparators    string // Deprecated: Use Tags.genre.Split instead
 	GroupAlbumReleases bool   // Deprecated: Use PID.Album instead
 	FollowSymlinks     bool   // Whether to follow symlinks when scanning directories
+	IgnoreDotFolders   bool   // Whether to ignore folders whose name starts with a dot when scanning
 	PurgeMissing       string // Values: "never", "always", "full"
 }
 
@@ -776,7 +777,7 @@ func setViperDefaults() {
 	viper.SetDefault("artistartpriority", "artist.*, album/artist.*, external")
 	viper.SetDefault("artistimagefolder", "")
 	viper.SetDefault("discartpriority", "disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded")
-	viper.SetDefault("lyricspriority", ".lrc,.txt,embedded")
+	viper.SetDefault("lyricspriority", ".ttml,.yaml,.yml,.elrc,.lrc,.srt,.txt,embedded")
 	viper.SetDefault("enablegravatar", false)
 	viper.SetDefault("enablefavourites", true)
 	viper.SetDefault("enablestarrating", true)
@@ -821,6 +822,7 @@ func setViperDefaults() {
 	viper.SetDefault("scanner.genreseparators", "")
 	viper.SetDefault("scanner.groupalbumreleases", false)
 	viper.SetDefault("scanner.followsymlinks", true)
+	viper.SetDefault("scanner.ignoredotfolders", true)
 	viper.SetDefault("scanner.purgemissing", consts.PurgeMissingNever)
 	viper.SetDefault("subsonic.appendsubtitle", true)
 	viper.SetDefault("subsonic.appendalbumversion", true)

consts/consts.go

@@ -14,6 +14,9 @@ const (
 	DefaultDbPath                 = "navidrome.db?cache=shared&_busy_timeout=15000&_journal_mode=WAL&_foreign_keys=on&synchronous=normal"
 	InitialSetupFlagKey           = "InitialSetup"
 	FullScanAfterMigrationFlagKey = "FullScanAfterMigration"
+	// PlaylistsImportPendingFlagKey marks that playlist import was deferred because
+	// no admin user existed yet; the next scan with an admin imports them.
+	PlaylistsImportPendingFlagKey = "PlaylistsImportPending"
 	LastScanErrorKey              = "LastScanError"
 	LastScanTypeKey               = "LastScanType"
 	LastScanStartTimeKey          = "LastScanStartTime"
@@ -153,25 +156,25 @@ var (
 			Name:           "mp3 audio",
 			TargetFormat:   "mp3",
 			DefaultBitRate: 192,
-			Command:        "ffmpeg -ss %t -i %s -map 0:a:0 -b:a %bk -v 0 -f mp3 -",
+			Command:        "ffmpeg -ss %t -i %s -map 0:a:0 -map_metadata 0 -map_metadata 0:s:a:0 -b:a %bk -v 0 -f mp3 -",
 		},
 		{
 			Name:           "opus audio",
 			TargetFormat:   "opus",
 			DefaultBitRate: 128,
-			Command:        "ffmpeg -ss %t -i %s -map 0:a:0 -b:a %bk -v 0 -c:a libopus -f opus -",
+			Command:        "ffmpeg -ss %t -i %s -map 0:a:0 -map_metadata 0 -map_metadata 0:s:a:0 -b:a %bk -v 0 -c:a libopus -f opus -",
 		},
 		{
 			Name:           "aac audio",
 			TargetFormat:   "aac",
 			DefaultBitRate: 256,
-			Command:        "ffmpeg -ss %t -i %s -map 0:a:0 -b:a %bk -v 0 -c:a aac -f adts -",
+			Command:        "ffmpeg -ss %t -i %s -map 0:a:0 -map_metadata 0 -map_metadata 0:s:a:0 -b:a %bk -v 0 -c:a aac -f adts -",
 		},
 		{
 			Name:           "flac audio",
 			TargetFormat:   "flac",
 			DefaultBitRate: 0,
-			Command:        "ffmpeg -ss %t -i %s -map 0:a:0 -v 0 -c:a flac -f flac -",
+			Command:        "ffmpeg -ss %t -i %s -map 0:a:0 -map_metadata 0 -map_metadata 0:s:a:0 -v 0 -c:a flac -f flac -",
 		},
 	}
 )

core/artwork/reader_resized.go

@@ -132,6 +132,22 @@ func (a *resizedArtworkReader) resizeImage(ctx context.Context, reader io.Reader
 	return resizeStaticImage(data, a.size, a.square)
 }
 
+// toFastScaleType converts images whose concrete type has no optimized scaler
+// in x/image/draw (e.g. *image.NYCbCrA from WebP, *image.Paletted from indexed
+// PNGs) into *image.RGBA, which has a fast path. Without this, CatmullRom.Scale
+// falls back to a generic per-pixel At()/RGBA() loop that is several times
+// slower. Fast-path types are returned unchanged.
+func toFastScaleType(img image.Image) image.Image {
+	switch img.(type) {
+	case *image.RGBA, *image.NRGBA, *image.Gray, *image.YCbCr:
+		return img
+	default:
+		rgba := image.NewRGBA(img.Bounds())
+		draw.Draw(rgba, rgba.Bounds(), img, img.Bounds().Min, draw.Src)
+		return rgba
+	}
+}
+
 func resizeStaticImage(data []byte, size int, square bool) (io.Reader, int, error) {
 	original, format, err := image.Decode(bytes.NewReader(data))
 	if err != nil {
@@ -169,6 +185,7 @@ func resizeStaticImage(data []byte, size int, square bool) (io.Reader, int, erro
 		dst = image.NewNRGBA(image.Rect(0, 0, dstW, dstH))
 		dstRect = dst.Bounds()
 	}
+	original = toFastScaleType(original)
 	xdraw.CatmullRom.Scale(dst, dstRect, original, bounds, draw.Src, nil)
 
 	buf := bufPool.Get().(*bytes.Buffer)

core/external/provider_similarsongs_test.go

@@ -3,6 +3,7 @@ package external_test
 import (
 	"context"
 	"errors"
+	"strings"
 
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/core/agents"
@@ -56,7 +57,14 @@ var _ = Describe("Provider - SimilarSongs", 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"}
+
+				// Depeche Mode artist row used by matcher artist resolution and track-fetch back-mapping.
+				dmArtist := model.Artist{ID: "dm-1", Name: "Depeche Mode", OrderArtistName: "depeche mode", MbzArtistID: "artist-mbid"}
+				dmParticipant := model.Participant{Artist: dmArtist}
+				matchedSong := model.MediaFile{
+					ID: "matched-1", Title: "Dreaming of Me", Artist: "Depeche Mode",
+					Participants: model.Participants{model.RoleArtist: model.ParticipantList{dmParticipant}},
+				}
 
 				// GetEntityByID tries Artist, Album, Playlist, then MediaFile
 				artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
@@ -68,13 +76,16 @@ var _ = Describe("Provider - SimilarSongs", func() {
 						{Name: "Dreaming of Me", MBID: "", Artist: "Depeche Mode", ArtistMBID: "artist-mbid"},
 					}, nil).Once()
 
-				// Mock loadTracksByID - no ID matches
+				// Matcher artist resolution: resolve Depeche Mode in the artist table.
+				artistRepo.On("GetAll", mock.Anything).Return(model.Artists{dmArtist}, nil).Maybe()
+
+				// ID phase: no IDs → squirrel.And with media_file.id; won't be called but guard it.
 				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
 					_, ok := opt.Filters.(squirrel.Eq)
 					return ok
-				})).Return(model.MediaFiles{}, nil).Once()
+				})).Return(model.MediaFiles{}, nil).Maybe()
 
-				// Mock loadTracksByMBID - no MBID matches (empty MBID means this won't be called)
+				// MBID phase: won't fire (empty MBID).
 				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
 					and, ok := opt.Filters.(squirrel.And)
 					if !ok || len(and) < 1 {
@@ -88,18 +99,19 @@ var _ = Describe("Provider - SimilarSongs", func() {
 					return hasMBID
 				})).Return(model.MediaFiles{}, nil).Maybe()
 
-				// Mock loadTracksByTitleAndArtist - queries by artist name
+				// Matcher track-fetch: subquery returns the matched song with participants.
 				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
 					and, ok := opt.Filters.(squirrel.And)
-					if !ok || len(and) < 2 {
+					if !ok {
 						return false
 					}
-					eq, hasEq := and[0].(squirrel.Eq)
-					if !hasEq {
-						return false
+					for _, f := range and {
+						sql, _, err := f.ToSql()
+						if err == nil && strings.Contains(sql, "media_file_artists") {
+							return true
+						}
 					}
-					_, hasArtist := eq["order_artist_name"]
-					return hasArtist
+					return false
 				})).Return(model.MediaFiles{matchedSong}, nil).Maybe()
 
 				songs, err := provider.SimilarSongs(ctx, "track-1", 5)

core/external/provider_topsongs_test.go

@@ -148,6 +148,8 @@ var _ = Describe("Provider - TopSongs", func() {
 		// Mock finding the artist
 		artist1 := model.Artist{ID: "artist-1", Name: "Artist One", MbzArtistID: "mbid-artist-1"}
 		artistRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.Artists{artist1}, nil).Once()
+		// Matcher artist resolution for the title-match path (song2 falls through).
+		artistRepo.On("GetAll", mock.Anything).Return(model.Artists{artist1}, nil).Maybe()
 
 		// Mock agent response
 		agentSongs := []agents.Song{
@@ -159,7 +161,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		// Mock finding matching tracks (only find song 1 on bulk query)
 		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-song-1"}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once() // bulk MBID query
-		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{}, nil).Once()      // title fallback for song2
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{}, nil).Once()      // title track-fetch for song2: no match
 
 		songs, err := p.TopSongs(ctx, "Artist One", 2)
 
@@ -195,6 +197,8 @@ var _ = Describe("Provider - TopSongs", func() {
 		// Mock finding the artist
 		artist1 := model.Artist{ID: "artist-1", Name: "Artist One", MbzArtistID: "mbid-artist-1"}
 		artistRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.Artists{artist1}, nil).Once()
+		// Matcher artist resolution for both title-fallback songs.
+		artistRepo.On("GetAll", mock.Anything).Return(model.Artists{artist1}, nil).Maybe()
 
 		// Mock agent response with songs that have NO MBID (empty string)
 		agentSongs := []agents.Song{
@@ -203,10 +207,16 @@ var _ = Describe("Provider - TopSongs", func() {
 		}
 		ag.On("GetArtistTopSongs", ctx, "artist-1", "Artist One", "mbid-artist-1", 2).Return(agentSongs, nil).Once()
 
-		// Since there are no MBIDs, loadTracksByMBID should not make any database call
-		// loadTracksByTitle should make a database call for title matching
-		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "", OrderTitle: "song one"}
-		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "", OrderTitle: "song two"}
+		// Title track-fetch: tracks must carry RoleArtist participants so back-mapping routes them.
+		participant1 := model.Participant{Artist: model.Artist{ID: "artist-1", Name: "Artist One", OrderArtistName: "artist one"}}
+		song1 := model.MediaFile{
+			ID: "song-1", Title: "Song One", Artist: "Artist One", ArtistID: "artist-1",
+			Participants: model.Participants{model.RoleArtist: model.ParticipantList{participant1}},
+		}
+		song2 := model.MediaFile{
+			ID: "song-2", Title: "Song Two", Artist: "Artist One", ArtistID: "artist-1",
+			Participants: model.Participants{model.RoleArtist: model.ParticipantList{participant1}},
+		}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
 
 		songs, err := p.TopSongs(ctx, "Artist One", 2)
@@ -224,6 +234,8 @@ var _ = Describe("Provider - TopSongs", func() {
 		// Mock finding the artist
 		artist1 := model.Artist{ID: "artist-1", Name: "Artist One", MbzArtistID: "mbid-artist-1"}
 		artistRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.Artists{artist1}, nil).Once()
+		// Matcher artist resolution for song2's title-fallback path.
+		artistRepo.On("GetAll", mock.Anything).Return(model.Artists{artist1}, nil).Maybe()
 
 		// Mock agent response with mixed MBID availability
 		agentSongs := []agents.Song{
@@ -236,8 +248,12 @@ var _ = Describe("Provider - TopSongs", func() {
 		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-song-1", OrderTitle: "song one"}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once()
 
-		// Mock the title fallback query (finds song2 by title)
-		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "", OrderTitle: "song two"}
+		// Title track-fetch: song2 must carry RoleArtist participants for back-mapping.
+		participant1 := model.Participant{Artist: model.Artist{ID: "artist-1", Name: "Artist One", OrderArtistName: "artist one"}}
+		song2 := model.MediaFile{
+			ID: "song-2", Title: "Song Two", Artist: "Artist One", ArtistID: "artist-1",
+			Participants: model.Participants{model.RoleArtist: model.ParticipantList{participant1}},
+		}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song2}, nil).Once()
 
 		songs, err := p.TopSongs(ctx, "Artist One", 2)

core/ffmpeg/ffmpeg.go

@@ -403,6 +403,14 @@ func buildDynamicArgs(opts TranscodeOptions) []string {
 	args = append(args, "-i", opts.FilePath)
 	args = append(args, "-map", "0:a:0")
 
+	// Preserve source tags. -map_metadata 0 copies format-level tags (MP3/FLAC);
+	// -map_metadata 0:s:a:0 copies tags from the first audio stream (OPUS/OGG).
+	// Both are needed because the two source families store tags at different
+	// levels. Targeting the audio stream explicitly (s:a:0 rather than s:0) avoids
+	// pulling metadata from an embedded cover-art/video stream at index 0. Note:
+	// adts (AAC) output cannot hold tags, so these are a no-op there.
+	args = append(args, "-map_metadata", "0", "-map_metadata", "0:s:a:0")
+
 	if codec, ok := formatCodecMap[opts.Format]; ok {
 		args = append(args, "-c:a", codec)
 	}

core/ffmpeg/ffmpeg_test.go

@@ -82,16 +82,16 @@ var _ = Describe("ffmpeg", func() {
 
 	Describe("isDefaultCommand", func() {
 		It("returns true for known default mp3 command", func() {
-			Expect(isDefaultCommand("mp3", "ffmpeg -ss %t -i %s -map 0:a:0 -b:a %bk -v 0 -f mp3 -")).To(BeTrue())
+			Expect(isDefaultCommand("mp3", "ffmpeg -ss %t -i %s -map 0:a:0 -map_metadata 0 -map_metadata 0:s:a:0 -b:a %bk -v 0 -f mp3 -")).To(BeTrue())
 		})
 		It("returns true for known default opus command", func() {
-			Expect(isDefaultCommand("opus", "ffmpeg -ss %t -i %s -map 0:a:0 -b:a %bk -v 0 -c:a libopus -f opus -")).To(BeTrue())
+			Expect(isDefaultCommand("opus", "ffmpeg -ss %t -i %s -map 0:a:0 -map_metadata 0 -map_metadata 0:s:a:0 -b:a %bk -v 0 -c:a libopus -f opus -")).To(BeTrue())
 		})
 		It("returns true for known default aac command", func() {
-			Expect(isDefaultCommand("aac", "ffmpeg -ss %t -i %s -map 0:a:0 -b:a %bk -v 0 -c:a aac -f adts -")).To(BeTrue())
+			Expect(isDefaultCommand("aac", "ffmpeg -ss %t -i %s -map 0:a:0 -map_metadata 0 -map_metadata 0:s:a:0 -b:a %bk -v 0 -c:a aac -f adts -")).To(BeTrue())
 		})
 		It("returns true for known default flac command", func() {
-			Expect(isDefaultCommand("flac", "ffmpeg -ss %t -i %s -map 0:a:0 -v 0 -c:a flac -f flac -")).To(BeTrue())
+			Expect(isDefaultCommand("flac", "ffmpeg -ss %t -i %s -map 0:a:0 -map_metadata 0 -map_metadata 0:s:a:0 -v 0 -c:a flac -f flac -")).To(BeTrue())
 		})
 		It("returns false for a custom command", func() {
 			Expect(isDefaultCommand("mp3", "ffmpeg -i %s -b:a %bk -custom-flag -f mp3 -")).To(BeFalse())
@@ -113,6 +113,7 @@ var _ = Describe("ffmpeg", func() {
 			Expect(args).To(Equal([]string{
 				"ffmpeg", "-i", "/music/file.flac",
 				"-map", "0:a:0",
+				"-map_metadata", "0", "-map_metadata", "0:s:a:0",
 				"-c:a", "libmp3lame",
 				"-b:a", "256k",
 				"-ar", "48000",
@@ -132,6 +133,7 @@ var _ = Describe("ffmpeg", func() {
 			Expect(args).To(Equal([]string{
 				"ffmpeg", "-i", "/music/file.dsf",
 				"-map", "0:a:0",
+				"-map_metadata", "0", "-map_metadata", "0:s:a:0",
 				"-c:a", "flac",
 				"-ar", "48000",
 				"-v", "0",
@@ -149,6 +151,7 @@ var _ = Describe("ffmpeg", func() {
 			Expect(args).To(Equal([]string{
 				"ffmpeg", "-i", "/music/file.flac",
 				"-map", "0:a:0",
+				"-map_metadata", "0", "-map_metadata", "0:s:a:0",
 				"-c:a", "libopus",
 				"-b:a", "128k",
 				"-v", "0",
@@ -169,6 +172,7 @@ var _ = Describe("ffmpeg", func() {
 				"-ss", "30",
 				"-i", "/music/file.mp3",
 				"-map", "0:a:0",
+				"-map_metadata", "0", "-map_metadata", "0:s:a:0",
 				"-c:a", "libmp3lame",
 				"-b:a", "192k",
 				"-v", "0",
@@ -186,6 +190,7 @@ var _ = Describe("ffmpeg", func() {
 			Expect(args).To(Equal([]string{
 				"ffmpeg", "-i", "/music/file.flac",
 				"-map", "0:a:0",
+				"-map_metadata", "0", "-map_metadata", "0:s:a:0",
 				"-c:a", "aac",
 				"-b:a", "256k",
 				"-v", "0",
@@ -203,6 +208,7 @@ var _ = Describe("ffmpeg", func() {
 			Expect(args).To(Equal([]string{
 				"ffmpeg", "-i", "/music/file.dsf",
 				"-map", "0:a:0",
+				"-map_metadata", "0", "-map_metadata", "0:s:a:0",
 				"-c:a", "flac",
 				"-sample_fmt", "s32",
 				"-v", "0",

core/library.go

@@ -253,7 +253,11 @@ func (r *libraryRepositoryWrapper) Delete(id string) error {
 		return r.mapError(err)
 	}
 
-	err = r.LibraryRepository.Delete(libID)
+	// Run the deletion in a transaction so the cascade delete and the orphaned-artist
+	// reconciliation it triggers (see libraryRepository.Delete) commit atomically.
+	err = r.ds.WithTx(func(tx model.DataStore) error {
+		return tx.Library(r.ctx).Delete(libID)
+	}, "delete library")
 	if err != nil {
 		return r.mapError(err)
 	}

core/lyrics/lyrics.go

@@ -4,56 +4,122 @@ import (
 	"context"
 	"strings"
 
+	. "github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/persistence"
 )
 
-// Lyrics can fetch lyrics for a media file.
-type Lyrics interface {
+// maxLegacyLyricsCandidates bounds the duplicate window scanned by the legacy
+// artist/title lookup, so source-priority resolution can still reach older
+// matches without turning it into an unbounded table scan.
+const maxLegacyLyricsCandidates = 10
+
+// Provider fetches lyrics for a single media file. It is the contract
+// implemented by individual lyrics sources, such as plugins.
+type Provider interface {
 	GetLyrics(ctx context.Context, mf *model.MediaFile) (model.LyricList, error)
 }
 
+// Lyrics resolves lyrics for media files, honoring the configured source
+// priority.
+type Lyrics interface {
+	Provider
+	GetLyricsByArtistTitle(ctx context.Context, artist, title string) (model.LyricList, error)
+}
+
 // PluginLoader discovers and loads lyrics provider plugins.
 type PluginLoader interface {
-	LoadLyricsProvider(name string) (Lyrics, bool)
+	LoadLyricsProvider(name string) (Provider, bool)
 }
 
 type lyricsService struct {
+	ds           model.DataStore
 	pluginLoader PluginLoader
 }
 
 // NewLyrics creates a new lyrics service. pluginLoader may be nil if no plugin
 // system is available.
-func NewLyrics(pluginLoader PluginLoader) Lyrics {
-	return &lyricsService{pluginLoader: pluginLoader}
+func NewLyrics(ds model.DataStore, pluginLoader PluginLoader) Lyrics {
+	return &lyricsService{ds: ds, pluginLoader: pluginLoader}
 }
 
 // GetLyrics returns lyrics for the given media file, trying sources in the
 // order specified by conf.Server.LyricsPriority.
 func (l *lyricsService) GetLyrics(ctx context.Context, mf *model.MediaFile) (model.LyricList, error) {
-	var lyricsList model.LyricList
-	var err error
+	return l.getLyricsForCandidates(ctx, []*model.MediaFile{mf})
+}
 
+// GetLyricsByArtistTitle resolves lyrics for the legacy artist/title lookup,
+// scanning a bounded window of duplicate matches so source priority still wins
+// across them.
+func (l *lyricsService) GetLyricsByArtistTitle(ctx context.Context, artist, title string) (model.LyricList, error) {
+	opts := songsByArtistTitleWithLyricsFirst(artist, title)
+	opts.Max = maxLegacyLyricsCandidates
+	mediaFiles, err := l.ds.MediaFile(ctx).GetAll(opts)
+	if err != nil {
+		return nil, err
+	}
+	if len(mediaFiles) == 0 {
+		return nil, nil
+	}
+	candidates := make([]*model.MediaFile, 0, len(mediaFiles))
+	for i := range mediaFiles {
+		candidates = append(candidates, &mediaFiles[i])
+	}
+	return l.getLyricsForCandidates(ctx, candidates)
+}
+
+func songsByArtistTitleWithLyricsFirst(artist, title string) model.QueryOptions {
+	return model.QueryOptions{
+		Sort:  "lyrics, updated_at",
+		Order: "desc",
+		Filters: And{
+			Eq{"missing": false},
+			Eq{"title": title},
+			Or{
+				persistence.Exists("json_tree(participants, '$.albumartist')", Eq{"value": artist}),
+				persistence.Exists("json_tree(participants, '$.artist')", Eq{"value": artist}),
+			},
+		},
+	}
+}
+
+func (l *lyricsService) getLyricsForCandidates(ctx context.Context, mediaFiles []*model.MediaFile) (model.LyricList, error) {
 	for pattern := range strings.SplitSeq(conf.Server.LyricsPriority, ",") {
 		pattern = strings.TrimSpace(pattern)
-		switch {
-		case strings.EqualFold(pattern, "embedded"):
-			lyricsList, err = fromEmbedded(ctx, mf)
-		case strings.HasPrefix(pattern, "."):
-			lyricsList, err = fromExternalFile(ctx, mf, strings.ToLower(pattern))
-		default:
-			lyricsList, err = l.fromPlugin(ctx, mf, pattern)
+		if pattern == "" {
+			continue
 		}
 
-		if err != nil {
-			log.Error(ctx, "error getting lyrics", "source", pattern, err)
-		}
+		for _, mf := range mediaFiles {
+			if mf == nil {
+				continue
+			}
 
-		if len(lyricsList) > 0 {
-			return lyricsList, nil
+			lyricsList, err := l.getLyricsFromSource(ctx, mf, pattern)
+			if err != nil {
+				log.Error(ctx, "error getting lyrics", "source", pattern, err)
+				continue
+			}
+
+			if len(lyricsList) > 0 {
+				return lyricsList, nil
+			}
 		}
 	}
 
 	return nil, nil
 }
+
+func (l *lyricsService) getLyricsFromSource(ctx context.Context, mf *model.MediaFile, pattern string) (model.LyricList, error) {
+	switch {
+	case strings.EqualFold(pattern, "embedded"):
+		return fromEmbedded(ctx, mf)
+	case strings.HasPrefix(pattern, "."):
+		return fromExternalFile(ctx, mf, pattern)
+	default:
+		return l.fromPlugin(ctx, mf, pattern)
+	}
+}

core/lyrics/lyrics_suite_test.go

@@ -1,9 +1,13 @@
 package lyrics_test
 
 import (
+	"io/fs"
 	"testing"
 
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/storage/local"
 	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model/metadata"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -15,3 +19,17 @@ func TestLyrics(t *testing.T) {
 	RegisterFailHandler(Fail)
 	RunSpecs(t, "Lyrics Suite")
 }
+
+// core/storage/local calls log.Fatal if the default scanner extractor is unregistered
+// when constructing any localStorage. Register a no-op so storage.For("file://...") works
+// in tests without importing the real extractor.
+var _ = BeforeSuite(func() {
+	local.RegisterExtractor(consts.DefaultScannerExtractor, func(fs.FS, string) local.Extractor {
+		return &noopExtractor{}
+	})
+})
+
+type noopExtractor struct{}
+
+func (e *noopExtractor) Parse(_ ...string) (map[string]metadata.Info, error) { return nil, nil }
+func (e *noopExtractor) Version() string                                     { return "noop" }

core/lyrics/lyrics_test.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"path/filepath"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -16,13 +17,14 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-var _ = Describe("sources", func() {
+var _ = Describe("Lyrics", func() {
 	var mf model.MediaFile
 	var ctx context.Context
 
 	const badLyrics = "This is a set of lyrics\nThat is not good"
-	unsynced, _ := model.ToLyrics("xxx", badLyrics)
-	embeddedLyrics := model.LyricList{*unsynced}
+	unsyncedList, _ := model.ParseLyrics(".lrc", "xxx", []byte(badLyrics))
+	unsynced, _ := unsyncedList.Main()
+	embeddedLyrics := model.LyricList{unsynced}
 
 	syncedLyrics := model.LyricList{
 		model.Lyrics{
@@ -44,6 +46,71 @@ var _ = Describe("sources", func() {
 		},
 	}
 
+	elrcLyrics := model.LyricList{
+		model.Lyrics{
+			DisplayArtist: "ELRC Artist",
+			DisplayTitle:  "ELRC Song",
+			Lang:          "eng",
+			Line: []model.Line{
+				{
+					Start: new(int64(1000)),
+					End:   new(int64(3000)),
+					Value: "Lead words",
+					Cue: []model.Cue{
+						{
+							Start:     new(int64(1000)),
+							End:       new(int64(1500)),
+							Value:     "Lead ",
+							ByteStart: 0,
+							ByteEnd:   4,
+						},
+						{
+							Start:     new(int64(1500)),
+							End:       new(int64(3000)),
+							Value:     "words",
+							ByteStart: 5,
+							ByteEnd:   9,
+						},
+					},
+				},
+				{
+					Start: new(int64(3000)),
+					Value: "Fallback line",
+				},
+			},
+			Synced: true,
+		},
+	}
+
+	ttmlLyrics := model.LyricList{
+		model.Lyrics{
+			Kind: "main",
+			Lang: "eng",
+			Line: []model.Line{
+				{
+					Start: new(int64(18800)),
+					Value: "We're no strangers to love",
+				},
+				{
+					Start: new(int64(22800)),
+					Value: "You know the rules and so do I",
+				},
+			},
+			Synced: true,
+		},
+		model.Lyrics{
+			Kind: "main",
+			Lang: "por",
+			Line: []model.Line{
+				{
+					Start: new(int64(18800)),
+					Value: "Nao somos estranhos ao amor",
+				},
+			},
+			Synced: true,
+		},
+	}
+
 	unsyncedLyrics := model.LyricList{
 		model.Lyrics{
 			Lang: "xxx",
@@ -59,6 +126,25 @@ var _ = Describe("sources", func() {
 		},
 	}
 
+	srtLyrics := model.LyricList{
+		model.Lyrics{
+			Lang: "xxx",
+			Line: []model.Line{
+				{
+					Start: new(int64(18800)),
+					End:   new(int64(22800)),
+					Value: "We're from subtitles",
+				},
+				{
+					Start: new(int64(22801)),
+					End:   new(int64(26000)),
+					Value: "Another subtitle line",
+				},
+			},
+			Synced: true,
+		},
+	}
+
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 
@@ -68,19 +154,104 @@ var _ = Describe("sources", func() {
 			Lyrics: string(lyricsJson),
 			Path:   "tests/fixtures/test.mp3",
 		}
-		ctx = context.Background()
+		ctx = GinkgoT().Context()
 	})
 
 	DescribeTable("Lyrics Priority", func(priority string, expected model.LyricList) {
 		conf.Server.LyricsPriority = priority
-		svc := lyrics.NewLyrics(nil)
+		svc := lyrics.NewLyrics(nil, nil)
 		list, err := svc.GetLyrics(ctx, &mf)
 		Expect(err).To(BeNil())
 		Expect(list).To(Equal(expected))
 	},
 		Entry("embedded > lrc > txt", "embedded,.lrc,.txt", embeddedLyrics),
 		Entry("lrc > embedded > txt", ".lrc,embedded,.txt", syncedLyrics),
-		Entry("txt > lrc > embedded", ".txt,.lrc,embedded", unsyncedLyrics))
+		Entry("elrc > lrc > embedded", ".elrc,.lrc,embedded", elrcLyrics),
+		Entry("srt > txt > embedded", ".srt,.txt,embedded", srtLyrics),
+		Entry("txt > lrc > embedded", ".txt,.lrc,embedded", unsyncedLyrics),
+		Entry("ttml > elrc > lrc > srt > embedded", ".ttml,.elrc,.lrc,.srt,embedded", ttmlLyrics))
+
+	It("resolves source priority across duplicate media files", func() {
+		conf.Server.LyricsPriority = ".ttml,embedded"
+		embeddedJSON, err := json.Marshal(embeddedLyrics)
+		Expect(err).To(BeNil())
+
+		repo := &tests.MockMediaFileRepo{}
+		repo.SetData(model.MediaFiles{
+			{
+				Lyrics: string(embeddedJSON),
+				Path:   "tests/fixtures/01 Invisible (RED) Edit Version.mp3",
+			},
+			{
+				Lyrics: "[]",
+				Path:   "tests/fixtures/test.mp3",
+			},
+		})
+		svc := lyrics.NewLyrics(&tests.MockDataStore{MockedMediaFile: repo}, nil)
+
+		list, err := svc.GetLyricsByArtistTitle(ctx, "Rick Astley", "Never Gonna Give You Up")
+		Expect(err).To(BeNil())
+		Expect(list).To(Equal(ttmlLyrics))
+	})
+
+	It("preserves configured sidecar suffix casing on case-sensitive filesystems", func() {
+		dir, err := os.MkdirTemp("", "lyrics-case-*")
+		Expect(err).ToNot(HaveOccurred())
+		DeferCleanup(func() {
+			Expect(os.RemoveAll(dir)).To(Succeed())
+		})
+
+		probe := filepath.Join(dir, "CASECHECK")
+		Expect(os.WriteFile(probe, []byte("probe"), 0600)).To(Succeed())
+		_, err = os.Stat(filepath.Join(dir, "casecheck"))
+		if err == nil {
+			Skip("filesystem is case-insensitive")
+		}
+		Expect(os.IsNotExist(err)).To(BeTrue())
+
+		conf.Server.LyricsPriority = ".LRC"
+		Expect(os.WriteFile(filepath.Join(dir, "song.LRC"), []byte("[00:01.00]Upper suffix"), 0600)).To(Succeed())
+
+		svc := lyrics.NewLyrics(nil, nil)
+		list, err := svc.GetLyrics(ctx, &model.MediaFile{
+			LibraryPath: dir,
+			Path:        "song.mp3",
+		})
+
+		Expect(err).To(BeNil())
+		Expect(list).To(HaveLen(1))
+		Expect(list[0].Line).To(Equal([]model.Line{
+			{Start: new(int64(1000)), Value: "Upper suffix"},
+		}))
+	})
+
+	It("returns a non-Lyricsfile YAML sidecar as plain text, shadowing lower-priority sources", func() {
+		dir, err := os.MkdirTemp("", "lyrics-yaml-fallback-*")
+		Expect(err).ToNot(HaveOccurred())
+		DeferCleanup(func() {
+			Expect(os.RemoveAll(dir)).To(Succeed())
+		})
+
+		Expect(os.WriteFile(filepath.Join(dir, "song.yaml"), []byte("title: not lyricsfile\n"), 0600)).To(Succeed())
+		Expect(os.WriteFile(filepath.Join(dir, "song.lrc"), []byte("[00:01.00]Fallback line"), 0600)).To(Succeed())
+
+		conf.Server.LyricsPriority = ".yaml,.lrc"
+		svc := lyrics.NewLyrics(nil, nil)
+		list, err := svc.GetLyrics(ctx, &model.MediaFile{
+			LibraryPath: dir,
+			Path:        "song.mp3",
+		})
+
+		// ParseLyrics falls back to plain text for any suffix when the content
+		// doesn't match the structured format, so the .yaml hit is non-empty and
+		// shadows the lower-priority .lrc entirely.
+		Expect(err).To(BeNil())
+		Expect(list).To(HaveLen(1))
+		Expect(list[0].Synced).To(BeFalse())
+		Expect(list[0].Line).To(Equal([]model.Line{
+			{Value: "title: not lyricsfile"},
+		}))
+	})
 
 	Context("Errors", func() {
 		var RegularUserContext = XContext
@@ -110,7 +281,7 @@ var _ = Describe("sources", func() {
 			It("should fallback to embedded if an error happens when parsing file", func() {
 				conf.Server.LyricsPriority = ".mp3,embedded"
 
-				svc := lyrics.NewLyrics(nil)
+				svc := lyrics.NewLyrics(nil, nil)
 				list, err := svc.GetLyrics(ctx, &mf)
 				Expect(err).To(BeNil())
 				Expect(list).To(Equal(embeddedLyrics))
@@ -119,7 +290,7 @@ var _ = Describe("sources", func() {
 			It("should return nothing if error happens when trying to parse file", func() {
 				conf.Server.LyricsPriority = ".mp3"
 
-				svc := lyrics.NewLyrics(nil)
+				svc := lyrics.NewLyrics(nil, nil)
 				list, err := svc.GetLyrics(ctx, &mf)
 				Expect(err).To(BeNil())
 				Expect(list).To(BeEmpty())
@@ -137,7 +308,7 @@ var _ = Describe("sources", func() {
 		It("should return lyrics from a plugin", func() {
 			conf.Server.LyricsPriority = "test-lyrics-plugin"
 			mockLoader.lyrics = unsyncedLyrics
-			svc := lyrics.NewLyrics(mockLoader)
+			svc := lyrics.NewLyrics(nil, mockLoader)
 			list, err := svc.GetLyrics(ctx, &mf)
 			Expect(err).To(BeNil())
 			Expect(list).To(Equal(unsyncedLyrics))
@@ -147,7 +318,7 @@ var _ = Describe("sources", func() {
 			conf.Server.LyricsPriority = "embedded,test-lyrics-plugin"
 			mf.Lyrics = "" // No embedded lyrics
 			mockLoader.lyrics = unsyncedLyrics
-			svc := lyrics.NewLyrics(mockLoader)
+			svc := lyrics.NewLyrics(nil, mockLoader)
 			list, err := svc.GetLyrics(ctx, &mf)
 			Expect(err).To(BeNil())
 			Expect(list).To(Equal(unsyncedLyrics))
@@ -156,7 +327,7 @@ var _ = Describe("sources", func() {
 		It("should skip plugin if embedded has lyrics", func() {
 			conf.Server.LyricsPriority = "embedded,test-lyrics-plugin"
 			mockLoader.lyrics = unsyncedLyrics
-			svc := lyrics.NewLyrics(mockLoader)
+			svc := lyrics.NewLyrics(nil, mockLoader)
 			list, err := svc.GetLyrics(ctx, &mf)
 			Expect(err).To(BeNil())
 			Expect(list).To(Equal(embeddedLyrics)) // embedded wins
@@ -165,7 +336,7 @@ var _ = Describe("sources", func() {
 		It("should skip unknown plugin names gracefully", func() {
 			conf.Server.LyricsPriority = "nonexistent-plugin,embedded"
 			mockLoader.notFound = true
-			svc := lyrics.NewLyrics(mockLoader)
+			svc := lyrics.NewLyrics(nil, mockLoader)
 			list, err := svc.GetLyrics(ctx, &mf)
 			Expect(err).To(BeNil())
 			Expect(list).To(Equal(embeddedLyrics)) // falls through to embedded
@@ -175,7 +346,7 @@ var _ = Describe("sources", func() {
 			conf.Server.LyricsPriority = "MyLyricsPlugin"
 			mockLoader.pluginName = "MyLyricsPlugin"
 			mockLoader.lyrics = unsyncedLyrics
-			svc := lyrics.NewLyrics(mockLoader)
+			svc := lyrics.NewLyrics(nil, mockLoader)
 			list, err := svc.GetLyrics(ctx, &mf)
 			Expect(err).To(BeNil())
 			Expect(list).To(Equal(unsyncedLyrics))
@@ -184,12 +355,56 @@ var _ = Describe("sources", func() {
 		It("should handle plugin error gracefully", func() {
 			conf.Server.LyricsPriority = "test-lyrics-plugin,embedded"
 			mockLoader.err = fmt.Errorf("plugin error")
-			svc := lyrics.NewLyrics(mockLoader)
+			svc := lyrics.NewLyrics(nil, mockLoader)
 			list, err := svc.GetLyrics(ctx, &mf)
 			Expect(err).To(BeNil())
 			Expect(list).To(Equal(embeddedLyrics)) // falls through to embedded
 		})
 	})
+
+	var _ = Describe("GetLyricsByArtistTitle", func() {
+		var svc lyrics.Lyrics
+		var repo *tests.MockMediaFileRepo
+		var ds *tests.MockDataStore
+
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.LyricsPriority = "embedded"
+			repo = &tests.MockMediaFileRepo{}
+			ds = &tests.MockDataStore{MockedMediaFile: repo}
+			svc = lyrics.NewLyrics(ds, nil)
+		})
+
+		It("bounds the query to a duplicate window", func() {
+			repo.SetData(model.MediaFiles{})
+			_, err := svc.GetLyricsByArtistTitle(ctx, "Rick Astley", "Never Gonna Give You Up")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(repo.Options.Max).To(Equal(10))
+		})
+
+		It("returns nil when no media file matches", func() {
+			repo.SetData(model.MediaFiles{})
+			list, err := svc.GetLyricsByArtistTitle(ctx, "Nobody", "No Song")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(list).To(BeNil())
+		})
+
+		It("resolves lyrics from the matched media files", func() {
+			embeddedList, err := model.ParseLyrics(".lrc", "eng", []byte("Embedded lyrics line"))
+			Expect(err).ToNot(HaveOccurred())
+			embedded, _ := embeddedList.Main()
+			embeddedJSON, err := json.Marshal(model.LyricList{embedded})
+			Expect(err).ToNot(HaveOccurred())
+			repo.SetData(model.MediaFiles{
+				{ID: "1", Title: "Never Gonna Give You Up", Lyrics: string(embeddedJSON)},
+			})
+
+			list, err := svc.GetLyricsByArtistTitle(ctx, "Rick Astley", "Never Gonna Give You Up")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(list).To(HaveLen(1))
+			Expect(list[0].Line[0].Value).To(Equal("Embedded lyrics line"))
+		})
+	})
 })
 
 type mockPluginLoader struct {
@@ -206,7 +421,7 @@ func (m *mockPluginLoader) PluginNames(_ string) []string {
 	return []string{"test-lyrics-plugin"}
 }
 
-func (m *mockPluginLoader) LoadLyricsProvider(name string) (lyrics.Lyrics, bool) {
+func (m *mockPluginLoader) LoadLyricsProvider(name string) (lyrics.Provider, bool) {
 	if m.notFound {
 		return nil, false
 	}

core/lyrics/sources.go

@@ -3,9 +3,12 @@ package lyrics
 import (
 	"context"
 	"errors"
-	"os"
+	"fmt"
+	"io"
+	"io/fs"
 	"path"
 
+	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/ioutils"
@@ -23,31 +26,45 @@ func fromEmbedded(ctx context.Context, mf *model.MediaFile) (model.LyricList, er
 }
 
 func fromExternalFile(ctx context.Context, mf *model.MediaFile, suffix string) (model.LyricList, error) {
-	basePath := mf.AbsolutePath()
-	ext := path.Ext(basePath)
+	ext := path.Ext(mf.Path)
+	sidecarRelPath := mf.Path[0:len(mf.Path)-len(ext)] + suffix
 
-	externalLyric := basePath[0:len(basePath)-len(ext)] + suffix
+	store, err := storage.For(mf.LibraryPath)
+	if err != nil {
+		return nil, fmt.Errorf("getting storage for library: %w", err)
+	}
+	fsys, err := store.FS()
+	if err != nil {
+		return nil, fmt.Errorf("opening library filesystem: %w", err)
+	}
 
-	contents, err := ioutils.UTF8ReadFile(externalLyric)
-	if errors.Is(err, os.ErrNotExist) {
-		log.Trace(ctx, "no lyrics found at path", "path", externalLyric)
+	f, err := fsys.Open(sidecarRelPath)
+	if errors.Is(err, fs.ErrNotExist) {
+		log.Trace(ctx, "no lyrics found at path", "path", sidecarRelPath)
 		return nil, nil
 	} else if err != nil {
 		return nil, err
 	}
+	defer f.Close()
 
-	lyrics, err := model.ToLyrics("xxx", string(contents))
+	contents, err := io.ReadAll(ioutils.UTF8Reader(f))
 	if err != nil {
-		log.Error(ctx, "error parsing lyric external file", "path", externalLyric, err)
 		return nil, err
-	} else if lyrics == nil {
-		log.Trace(ctx, "empty lyrics from external file", "path", externalLyric)
+	}
+
+	list, err := model.ParseLyrics(suffix, "xxx", contents)
+	if err != nil {
+		log.Error(ctx, "error parsing external lyric file", "path", sidecarRelPath, err)
+		return nil, err
+	}
+
+	if len(list) == 0 {
+		log.Trace(ctx, "empty lyrics from external file", "path", sidecarRelPath)
 		return nil, nil
 	}
 
-	log.Trace(ctx, "retrieved lyrics from external file", "path", externalLyric)
-
-	return model.LyricList{*lyrics}, nil
+	log.Trace(ctx, "retrieved lyrics from external file", "path", sidecarRelPath)
+	return list, nil
 }
 
 // fromPlugin attempts to load lyrics from a plugin with the given name.

core/lyrics/sources_test.go

@@ -3,6 +3,7 @@ package lyrics
 import (
 	"context"
 	"encoding/json"
+	"path/filepath"
 
 	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
@@ -25,10 +26,12 @@ var _ = Describe("sources", func() {
 			const syncedLyrics = "[00:18.80]We're no strangers to love\n[00:22.801]You know the rules and so do I"
 			const unsyncedLyrics = "We're no strangers to love\nYou know the rules and so do I"
 
-			synced, _ := model.ToLyrics("eng", syncedLyrics)
-			unsynced, _ := model.ToLyrics("xxx", unsyncedLyrics)
+			syncedList, _ := model.ParseLyrics(".lrc", "eng", []byte(syncedLyrics))
+			unsyncedList, _ := model.ParseLyrics(".lrc", "xxx", []byte(unsyncedLyrics))
+			synced, _ := syncedList.Main()
+			unsynced, _ := unsyncedList.Main()
 
-			expectedList := model.LyricList{*synced, *unsynced}
+			expectedList := model.LyricList{synced, unsynced}
 			lyricsJson, err := json.Marshal(expectedList)
 
 			Expect(err).ToNot(HaveOccurred())
@@ -53,72 +56,51 @@ var _ = Describe("sources", func() {
 	})
 
 	Describe("fromExternalFile", func() {
+		var fixturesDir string
+
+		BeforeEach(func() {
+			// tests.Init sets CWD to the repo root, so "tests/fixtures" resolves correctly.
+			abs, err := filepath.Abs("tests/fixtures")
+			Expect(err).ToNot(HaveOccurred())
+			fixturesDir = abs
+		})
+
+		mf := func(name string) *model.MediaFile {
+			return &model.MediaFile{LibraryPath: fixturesDir, Path: name}
+		}
+
 		It("should return nil for lyrics that don't exist", func() {
-			mf := model.MediaFile{Path: "tests/fixtures/01 Invisible (RED) Edit Version.mp3"}
-			lyrics, err := fromExternalFile(ctx, &mf, ".lrc")
+			lyrics, err := fromExternalFile(ctx, mf("01 Invisible (RED) Edit Version.mp3"), ".lrc")
 
 			Expect(err).To(BeNil())
 			Expect(lyrics).To(HaveLen(0))
 		})
 
-		It("should return synchronized lyrics from a file", func() {
-			mf := model.MediaFile{Path: "tests/fixtures/test.mp3"}
-			lyrics, err := fromExternalFile(ctx, &mf, ".lrc")
+		// fromExternalFile delegates format parsing to model.ParseLyrics; the
+		// per-format parser output is covered exhaustively in the model package.
+		// Here we only verify each suffix is read from the library FS and routed.
+		DescribeTable("should read the sidecar file and route its suffix to a parser",
+			func(name, suffix string, expectSynced bool) {
+				lyrics, err := fromExternalFile(ctx, mf(name), suffix)
 
-			Expect(err).To(BeNil())
-			Expect(lyrics).To(Equal(model.LyricList{
-				model.Lyrics{
-					DisplayArtist: "Rick Astley",
-					DisplayTitle:  "That one song",
-					Lang:          "eng",
-					Line: []model.Line{
-						{
-							Start: new(int64(18800)),
-							Value: "We're no strangers to love",
-						},
-						{
-							Start: new(int64(22801)),
-							Value: "You know the rules and so do I",
-						},
-					},
-					Offset: new(int64(-100)),
-					Synced: true,
-				},
-			}))
-		})
-
-		It("should return unsynchronized lyrics from a file", func() {
-			mf := model.MediaFile{Path: "tests/fixtures/test.mp3"}
-			lyrics, err := fromExternalFile(ctx, &mf, ".txt")
-
-			Expect(err).To(BeNil())
-			Expect(lyrics).To(Equal(model.LyricList{
-				model.Lyrics{
-					Lang: "xxx",
-					Line: []model.Line{
-						{
-							Value: "We're no strangers to love",
-						},
-						{
-							Value: "You know the rules and so do I",
-						},
-					},
-					Synced: false,
-				},
-			}))
-		})
+				Expect(err).To(BeNil())
+				Expect(lyrics).ToNot(BeEmpty())
+				Expect(lyrics[0].Line).ToNot(BeEmpty())
+				Expect(lyrics[0].Synced).To(Equal(expectSynced))
+			},
+			Entry(".lrc synced", "test.mp3", ".lrc", true),
+			Entry(".elrc enhanced", "test.mp3", ".elrc", true),
+			Entry(".txt plain", "test.mp3", ".txt", false),
+			Entry(".srt subtitles", "test.mp3", ".srt", true),
+			Entry(".ttml multilingual", "test.mp3", ".ttml", true),
+			Entry(".yaml lyricsfile", "test.mp3", ".yaml", true),
+		)
 
 		It("should handle LRC files with UTF-8 BOM marker (issue #4631)", func() {
-			// The function looks for <basePath-without-ext><suffix>, so we need to pass
-			// a MediaFile with .mp3 path and look for .lrc suffix
-			mf := model.MediaFile{Path: "tests/fixtures/bom-test.mp3"}
-			lyrics, err := fromExternalFile(ctx, &mf, ".lrc")
+			lyrics, err := fromExternalFile(ctx, mf("bom-test.mp3"), ".lrc")
 
 			Expect(err).To(BeNil())
-			Expect(lyrics).ToNot(BeNil())
 			Expect(lyrics).To(HaveLen(1))
-
-			// The critical assertion: even with BOM, synced should be true
 			Expect(lyrics[0].Synced).To(BeTrue(), "Lyrics with BOM marker should be recognized as synced")
 			Expect(lyrics[0].Line).To(HaveLen(1))
 			Expect(lyrics[0].Line[0].Start).To(Equal(new(int64(0))))
@@ -126,14 +108,10 @@ var _ = Describe("sources", func() {
 		})
 
 		It("should handle UTF-16 LE encoded LRC files", func() {
-			mf := model.MediaFile{Path: "tests/fixtures/bom-utf16-test.mp3"}
-			lyrics, err := fromExternalFile(ctx, &mf, ".lrc")
+			lyrics, err := fromExternalFile(ctx, mf("bom-utf16-test.mp3"), ".lrc")
 
 			Expect(err).To(BeNil())
-			Expect(lyrics).ToNot(BeNil())
 			Expect(lyrics).To(HaveLen(1))
-
-			// UTF-16 should be properly converted to UTF-8
 			Expect(lyrics[0].Synced).To(BeTrue(), "UTF-16 encoded lyrics should be recognized as synced")
 			Expect(lyrics[0].Line).To(HaveLen(2))
 			Expect(lyrics[0].Line[0].Start).To(Equal(new(int64(18800))))
@@ -141,5 +119,31 @@ var _ = Describe("sources", func() {
 			Expect(lyrics[0].Line[1].Start).To(Equal(new(int64(22801))))
 			Expect(lyrics[0].Line[1].Value).To(Equal("You know the rules and so do I"))
 		})
+
+		It("should handle TTML files with UTF-8 BOM marker", func() {
+			lyrics, err := fromExternalFile(ctx, mf("bom-test.mp3"), ".ttml")
+
+			Expect(err).To(BeNil())
+			Expect(lyrics).To(HaveLen(1))
+			Expect(lyrics[0].Kind).To(Equal("main"))
+			Expect(lyrics[0].Synced).To(BeTrue())
+			Expect(lyrics[0].Line).To(HaveLen(1))
+			Expect(lyrics[0].Line[0].Start).To(Equal(new(int64(0))))
+			Expect(lyrics[0].Line[0].Value).To(Equal("BOM test line"))
+		})
+
+		It("should handle UTF-16 BE encoded TTML files", func() {
+			lyrics, err := fromExternalFile(ctx, mf("bom-utf16-test.mp3"), ".ttml")
+
+			Expect(err).To(BeNil())
+			Expect(lyrics).To(HaveLen(1))
+			Expect(lyrics[0].Kind).To(Equal("main"))
+			Expect(lyrics[0].Synced).To(BeTrue())
+			Expect(lyrics[0].Line).To(HaveLen(2))
+			Expect(lyrics[0].Line[0].Start).To(Equal(new(int64(18800))))
+			Expect(lyrics[0].Line[0].Value).To(Equal("UTF16 line one"))
+			Expect(lyrics[0].Line[1].Start).To(Equal(new(int64(22801))))
+			Expect(lyrics[0].Line[1].Value).To(Equal("UTF16 line two"))
+		})
 	})
 })

core/matcher/doc.go

@@ -0,0 +1,108 @@
+// Package matcher matches song results from external agents (Last.fm, Deezer,
+// etc.) to tracks in the local music library, prioritizing accuracy over recall.
+//
+// It exposes a single [Matcher] type with two entry points that share the same
+// matching algorithm:
+//
+//   - [Matcher.MatchSongs] returns an ordered, deduplicated slice of library
+//     tracks, capped at a requested count. Use it when presenting "similar
+//     songs" results to a client.
+//   - [Matcher.MatchSongsIndexed] returns a map from input-song index to matched
+//     track, with no deduplication. Use it when the caller needs to correlate
+//     each result back to its input position (e.g. to attach a per-song
+//     similarity score).
+//
+// # Algorithm Overview
+//
+// Each input song is resolved to its best-matching library track using four
+// strategies, applied in priority order. A song matched by a higher-priority
+// strategy is never reconsidered by a lower-priority one:
+//
+//  1. Direct ID match: songs with an ID are matched to a MediaFile by ID.
+//  2. MusicBrainz Recording ID (MBID) match: songs with an MBID are matched to
+//     tracks with the same mbz_recording_id.
+//  3. ISRC match: songs with an ISRC are matched to tracks carrying that ISRC tag.
+//  4. Title+Artist fuzzy match: remaining songs are matched by fuzzy string
+//     comparison with metadata-specificity scoring (see below).
+//
+// Priority order is ID > MBID > ISRC > Title+Artist, so more reliable
+// identifiers always take precedence over fuzzy text matching. Missing tracks
+// (those no longer present on disk) are never matched.
+//
+// # Fuzzy Matching Details
+//
+// Title+artist matching uses Jaro-Winkler similarity, with a threshold
+// configurable via conf.Server.Matcher.FuzzyThreshold (default 85%). A library
+// track must clear the title threshold to be considered. Candidates that clear
+// it are ranked by, in order:
+//
+//  1. Title similarity (Jaro-Winkler score, 0.0–1.0)
+//  2. Duration proximity (closer duration scores higher; 1.0 when the agent
+//     reports no duration)
+//  3. Preferred-track flag (enabled by conf.Server.Matcher.PreferStarred;
+//     prioritizes tracks that are starred or rated >= 4)
+//  4. Specificity level (0–5, based on metadata precision; higher is better)
+//  5. Album similarity (Jaro-Winkler, as the final tiebreaker)
+//
+// The specificity levels, from most to least specific, are:
+//
+//	Level 5: Title + Artist MBID + Album MBID
+//	Level 4: Title + Artist MBID + Album name (fuzzy)
+//	Level 3: Title + Artist name + Album name (fuzzy)
+//	Level 2: Title + Artist MBID
+//	Level 1: Title + Artist name
+//	Level 0: Title only
+//
+// The title phase always requires an agent artist to scope the library query, so
+// Level 0 does not mean "no artist": it applies when a candidate matches on title
+// but its own artist differs from the query's (e.g. a cover or a featured-artist
+// credit), leaving the title as the only shared field.
+//
+// Each input song is scored independently, so two songs with the same title and
+// artist but different durations can resolve to different library tracks (each
+// matches the track closest to its own duration).
+//
+// # Examples
+//
+// All examples below exercise the title+artist phase, where the interesting
+// behavior lives. (Identifier phases — ID, MBID, ISRC — are exact lookups that
+// always win over fuzzy matching; they need no illustration.)
+//
+// Title threshold — a near-miss title still matches; an exact-only threshold
+// rejects it:
+//
+//	Agent returns: {Name: "Bohemian Rhapsody", Artist: "Queen"}
+//	Library has:   {ID: "t1", Title: "Bohemian Rhapsody - Remastered", Artist: "Queen"}
+//	With threshold 85%: match succeeds (similarity ~0.87)
+//	With threshold 100%: no match (not an exact title)
+//
+// Specificity ranking — among candidates that clear the title threshold, a
+// better album match wins:
+//
+//	Agent returns: {Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"}
+//	Library has:
+//	  {ID: "t1", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "101"}       // Level 1
+//	  {ID: "t2", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"}  // Level 3
+//	Result: t2 (Level 3 beats Level 1 on the album match)
+//
+// Duration tiebreak — with title and artist equal, the closest duration wins,
+// so two near-identical input songs can resolve to different tracks:
+//
+//	Agent returns:
+//	  {Name: "Untitled", Artist: "Interpol", Duration: 245000}  // 4:05
+//	  {Name: "Untitled", Artist: "Interpol", Duration: 600000}  // 10:00 (a live take)
+//	Library has:
+//	  {ID: "studio", Title: "Untitled", Artist: "Interpol", Duration: 248}  // 4:08
+//	  {ID: "live",   Title: "Untitled", Artist: "Interpol", Duration: 602}  // 10:02
+//	Result: studio for the first song, live for the second
+//
+// Preferred track — when conf.Server.Matcher.PreferStarred is enabled, a
+// starred (or rating >= 4) track is preferred even over a more specific match,
+// because the preferred flag outranks specificity:
+//
+//	Agent returns: {Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"}
+//	Library has:
+//	  {ID: "exact",   Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"}            // Level 3
+//	  {ID: "starred", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles", Starred: true} // Level 1, starred
+//	Result: starred (the preferred flag outranks the better album match)
+package matcher

core/matcher/matcher.go

@@ -3,12 +3,16 @@ package matcher
 import (
 	"context"
 	"fmt"
+	"maps"
 	"math"
+	"slices"
 
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/navidrome/navidrome/utils/str"
 	"github.com/xrash/smetrics"
 )
@@ -23,176 +27,73 @@ func New(ds model.DataStore) *Matcher {
 	return &Matcher{ds: ds}
 }
 
-// MatchSongs matches agent song results to local library tracks using a multi-phase
-// matching algorithm that prioritizes accuracy over recall.
+// MatchSongs matches agent songs to library tracks and returns up to count
+// tracks in the input's order. See the package documentation for the matching
+// algorithm.
 //
-// # Algorithm Overview
-//
-// The algorithm matches songs from external agents (Last.fm, Deezer, etc.) to tracks in the
-// local music library using four matching strategies in priority order:
-//
-//  1. Direct ID match: Songs with an ID field are matched directly to MediaFiles by ID
-//  2. MusicBrainz Recording ID (MBID) match: Songs with MBID are matched to tracks with
-//     matching mbz_recording_id
-//  3. ISRC match: Songs with ISRC are matched to tracks with matching ISRC tag
-//  4. Title+Artist fuzzy match: Remaining songs are matched using fuzzy string comparison
-//     with metadata specificity scoring
-//
-// # Matching Priority
-//
-// When selecting the final result, matches are prioritized in order: ID > MBID > ISRC > Title+Artist.
-// This ensures that more reliable identifiers take precedence over fuzzy text matching.
-//
-// # Fuzzy Matching Details
-//
-// For title+artist matching, the algorithm uses Jaro-Winkler similarity (threshold configurable
-// via Matcher.FuzzyThreshold, default 85%). Matches are ranked by:
-//
-//  1. Title similarity (Jaro-Winkler score, 0.0-1.0)
-//  2. Duration proximity (closer duration = higher score, 1.0 if unknown)
-//  3. Preferred track flag (enabled by Matcher.PreferStarred; prioritized when the track is
-//     starred or has rating >= 4)
-//  4. Specificity level (0-5, based on metadata precision):
-//     - Level 5: Title + Artist MBID + Album MBID (most specific)
-//     - Level 4: Title + Artist MBID + Album name (fuzzy)
-//     - Level 3: Title + Artist name + Album name (fuzzy)
-//     - Level 2: Title + Artist MBID
-//     - Level 1: Title + Artist name
-//     - Level 0: Title only
-//  5. Album similarity (Jaro-Winkler, as final tiebreaker)
-//
-// # Examples
-//
-// Example 1 - MBID Priority:
-//
-//	Agent returns: {Name: "Paranoid Android", MBID: "abc-123", Artist: "Radiohead"}
-//	Library has: [
-//	  {ID: "t1", Title: "Paranoid Android", MbzRecordingID: "abc-123"},
-//	  {ID: "t2", Title: "Paranoid Android", Artist: "Radiohead"},
-//	]
-//	Result: t1 (MBID match takes priority over title+artist)
-//
-// Example 2 - ISRC Priority:
-//
-//	Agent returns: {Name: "Paranoid Android", ISRC: "GBAYE0000351", Artist: "Radiohead"}
-//	Library has: [
-//	  {ID: "t1", Title: "Paranoid Android", Tags: {isrc: ["GBAYE0000351"]}},
-//	  {ID: "t2", Title: "Paranoid Android", Artist: "Radiohead"},
-//	]
-//	Result: t1 (ISRC match takes priority over title+artist)
-//
-// Example 3 - Specificity Ranking:
-//
-//	Agent returns: {Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"}
-//	Library has: [
-//	  {ID: "t1", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "101"},           // Level 1
-//	  {ID: "t2", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"},      // Level 3
-//	]
-//	Result: t2 (Level 3 beats Level 1 due to album match)
-//
-// Example 4 - Fuzzy Title Matching:
-//
-//	Agent returns: {Name: "Bohemian Rhapsody", Artist: "Queen"}
-//	Library has: {ID: "t1", Title: "Bohemian Rhapsody - Remastered", Artist: "Queen"}
-//	With threshold=85%: Match succeeds (similarity ~0.87)
-//	With threshold=100%: No match (not exact)
-//
-// # Parameters
-//
-//   - ctx: Context for database operations
-//   - songs: Slice of agent.Song results from external providers
-//   - count: Maximum number of matches to return
-//
-// # Returns
-//
-// Returns up to 'count' MediaFiles from the library that best match the input songs,
-// preserving the original order from the agent. Songs that cannot be matched are skipped.
+// Each library track appears at most once, unless the same input song is
+// repeated: identical input songs intentionally yield repeated output tracks,
+// while distinct songs that resolve to the same track are deduplicated. Songs
+// that cannot be matched are skipped.
 func (m *Matcher) MatchSongs(ctx context.Context, songs []agents.Song, count int) (model.MediaFiles, error) {
 	if len(songs) == 0 {
 		return nil, nil
 	}
-
-	byID, byMBID, byISRC, byTitle, err := m.loadAllMatches(ctx, songs)
+	matches, err := m.resolveMatches(ctx, songs)
 	if err != nil {
 		return nil, err
 	}
-	return m.selectBestMatchingSongs(songs, byID, byMBID, byISRC, byTitle, count), nil
+	return orderAndDedup(songs, matches, count), nil
 }
 
-// MatchSongsIndexed matches agent song results to local library tracks and returns a map
-// from input song index to matched MediaFile. Songs that cannot be matched are omitted from the map.
-// This preserves original indices, allowing callers to correlate results back to the input slice.
+// MatchSongsIndexed matches agent songs to library tracks and returns a map from
+// input-song index to matched track, letting callers correlate results back to
+// the input slice. Unmatched songs are omitted from the map. Unlike MatchSongs,
+// results are not deduplicated. See the package documentation for the matching
+// algorithm.
 func (m *Matcher) MatchSongsIndexed(ctx context.Context, songs []agents.Song) (map[int]model.MediaFile, error) {
 	if len(songs) == 0 {
 		return nil, nil
 	}
+	return m.resolveMatches(ctx, songs)
+}
 
-	byID, byMBID, byISRC, byTitle, err := m.loadAllMatches(ctx, songs)
-	if err != nil {
-		return nil, err
-	}
-
+// resolveMatches resolves each input song to its best-matching library track,
+// keyed by the song's index. Loaders run in priority order (ID > MBID > ISRC >
+// Title); each only fills indices not already matched by a higher-priority loader.
+func (m *Matcher) resolveMatches(ctx context.Context, songs []agents.Song) (map[int]model.MediaFile, error) {
 	result := make(map[int]model.MediaFile, len(songs))
-	for i, t := range songs {
-		if mf, found := findMatchingTrack(t, byID, byMBID, byISRC, byTitle); found {
-			result[i] = mf
+	if err := m.matchByID(ctx, songs, result); err != nil {
+		return nil, fmt.Errorf("failed to match tracks by ID: %w", err)
+	}
+	if err := m.matchByMBID(ctx, songs, result); err != nil {
+		return nil, fmt.Errorf("failed to match tracks by MBID: %w", err)
+	}
+	if err := m.matchByISRC(ctx, songs, result); err != nil {
+		return nil, fmt.Errorf("failed to match tracks by ISRC: %w", err)
+	}
+	// The title phase is best-effort: a DB failure there must not discard the exact
+	// matches already found by the higher-priority phases. Only surface it as fatal
+	// when nothing matched at all.
+	if err := m.matchByTitle(ctx, songs, result); err != nil {
+		if len(result) == 0 {
+			return nil, fmt.Errorf("failed to match tracks by title: %w", err)
 		}
+		log.Warn(ctx, "Title matching failed; returning matches from exact phases only", err)
 	}
 	return result, nil
 }
 
-func (m *Matcher) loadAllMatches(ctx context.Context, songs []agents.Song) (byID, byMBID, byISRC, byTitle map[string]model.MediaFile, err error) {
-	byID, err = m.loadTracksByID(ctx, songs)
-	if err != nil {
-		return nil, nil, nil, nil, fmt.Errorf("failed to load tracks by ID: %w", err)
-	}
-	byMBID, err = m.loadTracksByMBID(ctx, songs, byID)
-	if err != nil {
-		return nil, nil, nil, nil, fmt.Errorf("failed to load tracks by MBID: %w", err)
-	}
-	byISRC, err = m.loadTracksByISRC(ctx, songs, byID, byMBID)
-	if err != nil {
-		return nil, nil, nil, nil, fmt.Errorf("failed to load tracks by ISRC: %w", err)
-	}
-	byTitle, err = m.loadTracksByTitleAndArtist(ctx, songs, byID, byMBID, byISRC)
-	if err != nil {
-		return nil, nil, nil, nil, fmt.Errorf("failed to load tracks by title: %w", err)
-	}
-	return byID, byMBID, byISRC, byTitle, nil
-}
-
-// songMatchedIn checks if a song has already been matched in any of the provided match maps.
-func songMatchedIn(s agents.Song, priorMatches ...map[string]model.MediaFile) bool {
-	_, found := lookupByIdentifiers(s, priorMatches...)
-	return found
-}
-
-// lookupByIdentifiers searches for a song's identifiers (ID, MBID, ISRC) in the provided maps.
-func lookupByIdentifiers(s agents.Song, maps ...map[string]model.MediaFile) (model.MediaFile, bool) {
-	keys := []string{s.ID, s.MBID, s.ISRC}
-	for _, m := range maps {
-		for _, key := range keys {
-			if key != "" {
-				if mf, ok := m[key]; ok && mf.ID != "" {
-					return mf, true
-				}
-			}
-		}
-	}
-	return model.MediaFile{}, false
-}
-
-// loadTracksByID fetches MediaFiles from the library using direct ID matching.
-func (m *Matcher) loadTracksByID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
+// matchByID fills result with direct ID matches.
+func (m *Matcher) matchByID(ctx context.Context, songs []agents.Song, result map[int]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
+		return nil
 	}
 	res, err := m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
 		Filters: squirrel.And{
@@ -201,27 +102,37 @@ func (m *Matcher) loadTracksByID(ctx context.Context, songs []agents.Song) (map[
 		},
 	})
 	if err != nil {
-		return matches, err
+		return err
 	}
+	byID := make(map[string]model.MediaFile, len(res))
 	for _, mf := range res {
-		if _, ok := matches[mf.ID]; !ok {
-			matches[mf.ID] = mf
+		byID[mf.ID] = mf // media_file.id is unique, so no dedup needed
+	}
+	for i, s := range songs {
+		if s.ID == "" {
+			continue
+		}
+		if mf, ok := byID[s.ID]; ok {
+			result[i] = mf
 		}
 	}
-	return matches, nil
+	return nil
 }
 
-// loadTracksByMBID fetches MediaFiles from the library using MusicBrainz Recording IDs.
-func (m *Matcher) loadTracksByMBID(ctx context.Context, songs []agents.Song, priorMatches ...map[string]model.MediaFile) (map[string]model.MediaFile, error) {
+// matchByMBID fills result with MusicBrainz Recording ID matches, skipping
+// songs already matched by a higher-priority loader.
+func (m *Matcher) matchByMBID(ctx context.Context, songs []agents.Song, result map[int]model.MediaFile) error {
 	var mbids []string
-	for _, s := range songs {
-		if s.MBID != "" && !songMatchedIn(s, priorMatches...) {
+	for i, s := range songs {
+		if _, done := result[i]; done {
+			continue
+		}
+		if s.MBID != "" {
 			mbids = append(mbids, s.MBID)
 		}
 	}
-	matches := map[string]model.MediaFile{}
 	if len(mbids) == 0 {
-		return matches, nil
+		return nil
 	}
 	res, err := m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
 		Filters: squirrel.And{
@@ -230,45 +141,72 @@ func (m *Matcher) loadTracksByMBID(ctx context.Context, songs []agents.Song, pri
 		},
 	})
 	if err != nil {
-		return matches, err
+		return err
 	}
+	byMBID := make(map[string]model.MediaFile, len(res))
 	for _, mf := range res {
 		if id := mf.MbzRecordingID; id != "" {
-			if _, ok := matches[id]; !ok {
-				matches[id] = mf
+			if _, ok := byMBID[id]; !ok {
+				byMBID[id] = mf
 			}
 		}
 	}
-	return matches, nil
+	for i, s := range songs {
+		if _, done := result[i]; done {
+			continue
+		}
+		if s.MBID == "" {
+			continue
+		}
+		if mf, ok := byMBID[s.MBID]; ok {
+			result[i] = mf
+		}
+	}
+	return nil
 }
 
-// loadTracksByISRC fetches MediaFiles from the library using ISRC matching.
-func (m *Matcher) loadTracksByISRC(ctx context.Context, songs []agents.Song, priorMatches ...map[string]model.MediaFile) (map[string]model.MediaFile, error) {
+// matchByISRC fills result with ISRC tag matches, skipping songs already
+// matched by a higher-priority loader.
+func (m *Matcher) matchByISRC(ctx context.Context, songs []agents.Song, result map[int]model.MediaFile) error {
 	var isrcs []string
-	for _, s := range songs {
-		if s.ISRC != "" && !songMatchedIn(s, priorMatches...) {
+	for i, s := range songs {
+		if _, done := result[i]; done {
+			continue
+		}
+		if s.ISRC != "" {
 			isrcs = append(isrcs, s.ISRC)
 		}
 	}
-	matches := map[string]model.MediaFile{}
 	if len(isrcs) == 0 {
-		return matches, nil
+		return nil
 	}
 	res, err := m.ds.MediaFile(ctx).GetAllByTags(model.TagISRC, isrcs, model.QueryOptions{
 		Filters: squirrel.Eq{"missing": false},
 		Sort:    "starred desc, rating desc, year asc, compilation asc",
 	})
 	if err != nil {
-		return matches, err
+		return err
 	}
+	byISRC := make(map[string]model.MediaFile, len(res))
 	for _, mf := range res {
 		for _, isrc := range mf.Tags.Values(model.TagISRC) {
-			if _, ok := matches[isrc]; !ok {
-				matches[isrc] = mf
+			if _, ok := byISRC[isrc]; !ok {
+				byISRC[isrc] = mf
 			}
 		}
 	}
-	return matches, nil
+	for i, s := range songs {
+		if _, done := result[i]; done {
+			continue
+		}
+		if s.ISRC == "" {
+			continue
+		}
+		if mf, ok := byISRC[s.ISRC]; ok {
+			result[i] = mf
+		}
+	}
+	return nil
 }
 
 // songQuery represents a normalized query for matching a song to library tracks.
@@ -308,96 +246,234 @@ func (s matchScore) betterThan(other matchScore) bool {
 }
 
 // sanitizedTrack holds pre-sanitized fields for a media file, avoiding redundant sanitization
-// when the same track is scored against multiple queries in the inner loop. The `mf` field
-// is a pointer to avoid copying the large MediaFile struct into each entry of the per-artist
-// sanitized slice.
+// when the same track is scored against multiple queries. The `mf` field is a pointer to avoid
+// copying the large MediaFile struct into each entry of the sanitized slice.
 type sanitizedTrack struct {
-	mf     *model.MediaFile
-	title  string
-	artist string
-	album  string
+	mf         *model.MediaFile
+	title      string
+	artist     string
+	album      string
+	artistMBID string // resolved from the artist table; mf.MbzArtistID is not populated on the bulk path
 }
 
-func newSanitizedTrack(mf *model.MediaFile) sanitizedTrack {
+func newSanitizedTrack(mf *model.MediaFile, artistMBID string) sanitizedTrack {
 	return sanitizedTrack{
-		mf:     mf,
-		title:  str.SanitizeFieldForSorting(mf.Title),
-		artist: str.SanitizeFieldForSortingNoArticle(mf.Artist),
-		album:  str.SanitizeFieldForSorting(mf.Album),
+		mf:         mf,
+		title:      str.SanitizeFieldForSorting(mf.Title),
+		artist:     str.SanitizeFieldForSortingNoArticle(mf.Artist),
+		album:      str.SanitizeFieldForSorting(mf.Album),
+		artistMBID: artistMBID,
 	}
 }
 
 // computeSpecificityLevel determines how well query metadata matches a track (0-5).
-// The track's title, artist, and album fields must be pre-sanitized.
+// The track's title, artist, and album fields must be pre-sanitized, and artistMBID
+// must hold the resolved artist MBID.
 func computeSpecificityLevel(q songQuery, t sanitizedTrack, albumThreshold float64) int {
 	if q.artistMBID != "" && q.albumMBID != "" &&
-		t.mf.MbzArtistID == q.artistMBID && t.mf.MbzAlbumID == q.albumMBID {
+		t.artistMBID == q.artistMBID && t.mf.MbzAlbumID == q.albumMBID {
 		return 5
 	}
 	if q.artistMBID != "" && q.album != "" &&
-		t.mf.MbzArtistID == q.artistMBID && similarityRatio(t.album, q.album) >= albumThreshold {
+		t.artistMBID == q.artistMBID && similarityRatio(t.album, q.album) >= albumThreshold {
 		return 4
 	}
 	if q.artist != "" && q.album != "" &&
 		t.artist == q.artist && similarityRatio(t.album, q.album) >= albumThreshold {
 		return 3
 	}
-	if q.artistMBID != "" && t.mf.MbzArtistID == q.artistMBID {
+	if q.artistMBID != "" && t.artistMBID == q.artistMBID {
 		return 2
 	}
 	if q.artist != "" && t.artist == q.artist {
 		return 1
 	}
-	if t.title == q.title {
-		return 0
-	}
-	return -1
+	return 0
 }
 
-// loadTracksByTitleAndArtist loads tracks matching by title with optional artist/album filtering.
-func (m *Matcher) loadTracksByTitleAndArtist(ctx context.Context, songs []agents.Song, priorMatches ...map[string]model.MediaFile) (map[string]model.MediaFile, error) {
-	queries := m.buildTitleQueries(songs, priorMatches...)
-	if len(queries) == 0 {
-		return map[string]model.MediaFile{}, nil
+// indexedQuery pairs a normalized songQuery with the index of the input song
+// it came from, so title matches can be written back to result by index.
+type indexedQuery struct {
+	index int
+	query songQuery
+}
+
+// matchByTitle fills result with fuzzy title+artist matches, skipping songs
+// already matched by a higher-priority loader.
+func (m *Matcher) matchByTitle(ctx context.Context, songs []agents.Song, result map[int]model.MediaFile) error {
+	byArtist := groupQueriesByArtist(songs, result)
+	if len(byArtist) == 0 {
+		return nil
 	}
 
+	resolved, err := m.resolveArtists(ctx, byArtist)
+	if err != nil || len(resolved.allIDs) == 0 {
+		return err
+	}
+
+	tracks, err := m.fetchTracksCreditedTo(ctx, resolved.allIDs)
+	if err != nil {
+		return err
+	}
+
+	tracksByQuery := resolved.bucketTracks(tracks)
 	threshold := float64(conf.Server.Matcher.FuzzyThreshold) / 100.0
-
-	byArtist := map[string][]songQuery{}
-	for _, q := range queries {
-		if q.artist != "" {
-			byArtist[q.artist] = append(byArtist[q.artist], q)
-		}
-	}
-
-	matches := map[string]model.MediaFile{}
-	for artist, artistQueries := range byArtist {
-		tracks, err := m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
-			Filters: squirrel.And{
-				squirrel.Eq{"order_artist_name": artist},
-				squirrel.Eq{"missing": false},
-			},
-			Sort: "starred desc, rating desc, year asc, compilation asc",
-		})
-		if err != nil {
-			continue
-		}
-
-		sanitized := make([]sanitizedTrack, len(tracks))
-		for i := range tracks {
-			sanitized[i] = newSanitizedTrack(&tracks[i])
-		}
-
-		for _, q := range artistQueries {
-			if mf, found := m.findBestMatch(q, sanitized, threshold); found {
-				key := q.title + "|" + q.artist
-				if _, exists := matches[key]; !exists {
-					matches[key] = mf
-				}
+	for artist, queries := range byArtist {
+		sanitized := tracksByQuery[artist]
+		// Each song is matched independently by index, so two songs with the same
+		// (title, artist) but different durations can resolve to different tracks.
+		for _, iq := range queries {
+			if mf, found := m.findBestMatch(iq.query, sanitized, threshold); found {
+				result[iq.index] = mf
 			}
 		}
 	}
-	return matches, nil
+	return nil
+}
+
+// groupQueriesByArtist buckets the still-unmatched title queries by sanitized artist name.
+// Songs without an artist are skipped: title matching needs one to scope the library query.
+func groupQueriesByArtist(songs []agents.Song, result map[int]model.MediaFile) map[string][]indexedQuery {
+	byArtist := map[string][]indexedQuery{}
+	for i, s := range songs {
+		if _, done := result[i]; done {
+			continue
+		}
+		artist := str.SanitizeFieldForSortingNoArticle(s.Artist)
+		if artist == "" {
+			continue
+		}
+		byArtist[artist] = append(byArtist[artist], indexedQuery{index: i, query: songQuery{
+			title:      str.SanitizeFieldForSorting(s.Name),
+			artist:     artist,
+			artistMBID: s.ArtistMBID,
+			album:      str.SanitizeFieldForSorting(s.Album),
+			albumMBID:  s.AlbumMBID,
+			durationMs: s.Duration,
+		}})
+	}
+	return byArtist
+}
+
+// resolvedArtists holds the agent artists resolved to artist-table rows. Everything routes by
+// stable artist ID, never by name, so MBID-resolved artists whose order name differs from the
+// query name are not misrouted.
+type resolvedArtists struct {
+	byQuery map[string]map[string]struct{} // sanitized query name -> set of resolved artist IDs
+	mbid    map[string]string              // artist ID -> its MBID (the real one, from the artist table)
+	allIDs  []string                       // every resolved artist ID, for the track lookup
+}
+
+// resolveArtists resolves the queries' artists against the artist table (by sort name or
+// agent-provided MBID) and records, for each query, which artist IDs it owns.
+func (m *Matcher) resolveArtists(ctx context.Context, byArtist map[string][]indexedQuery) (resolvedArtists, error) {
+	names := make([]string, 0, len(byArtist))
+	mbidToQueries := make(map[string][]string, len(byArtist)) // agent ArtistMBID -> query names that supplied it
+	for name, queries := range byArtist {
+		names = append(names, name)
+		for _, iq := range queries {
+			if iq.query.artistMBID != "" {
+				mbidToQueries[iq.query.artistMBID] = append(mbidToQueries[iq.query.artistMBID], name)
+			}
+		}
+	}
+
+	filter := squirrel.Or{squirrel.Eq{"order_artist_name": names}}
+	if len(mbidToQueries) > 0 {
+		filter = append(filter, squirrel.Eq{"mbz_artist_id": slices.Collect(maps.Keys(mbidToQueries))})
+	}
+	artists, err := m.ds.Artist(ctx).GetAll(model.QueryOptions{Filters: filter})
+	if err != nil {
+		return resolvedArtists{}, err
+	}
+
+	res := resolvedArtists{
+		byQuery: make(map[string]map[string]struct{}, len(byArtist)),
+		mbid:    make(map[string]string, len(artists)),
+		allIDs:  make([]string, 0, len(artists)),
+	}
+	for _, a := range artists {
+		res.mbid[a.ID] = a.MbzArtistID
+		res.allIDs = append(res.allIDs, a.ID)
+		// An artist belongs to a query if its order name matches the query name, or if its MBID
+		// matches one a query supplied. The same MBID can come from several queries (agent aliases),
+		// so every one of them owns the artist.
+		res.own(a.OrderArtistName, a.ID)
+		if a.MbzArtistID != "" {
+			for _, name := range mbidToQueries[a.MbzArtistID] {
+				res.own(name, a.ID)
+			}
+		}
+	}
+	return res, nil
+}
+
+// own records that the named query owns the given artist ID. A name that is not a query simply
+// gets its own (unused) entry.
+func (r resolvedArtists) own(name, artistID string) {
+	if r.byQuery[name] == nil {
+		r.byQuery[name] = map[string]struct{}{}
+	}
+	r.byQuery[name][artistID] = struct{}{}
+}
+
+// bucketTracks groups tracks by query name, at most once per query even when a track credits
+// several of that query's artists, so the same track is not scored twice. The participants JSON
+// on each track carries artist IDs but not their MBID, so the MBID comes from r.mbid instead.
+func (r resolvedArtists) bucketTracks(tracks []model.MediaFile) map[string][]sanitizedTrack {
+	// Invert byQuery once so each participant maps straight to the queries that own it, instead of
+	// scanning every query per participant.
+	queriesByArtist := make(map[string][]string)
+	for name, ids := range r.byQuery {
+		for id := range ids {
+			queriesByArtist[id] = append(queriesByArtist[id], name)
+		}
+	}
+
+	byQuery := make(map[string][]sanitizedTrack, len(r.byQuery))
+	added := make(map[string]map[string]struct{}, len(r.byQuery)) // query name -> set of track IDs already bucketed
+	for i := range tracks {
+		for _, p := range tracks[i].Participants[model.RoleArtist] {
+			mbid, isResolved := r.mbid[p.ID]
+			if !isResolved {
+				continue
+			}
+			for _, name := range queriesByArtist[p.ID] {
+				if added[name] == nil {
+					added[name] = map[string]struct{}{}
+				}
+				if _, dup := added[name][tracks[i].ID]; dup {
+					continue
+				}
+				added[name][tracks[i].ID] = struct{}{}
+				byQuery[name] = append(byQuery[name], newSanitizedTrack(&tracks[i], mbid))
+			}
+		}
+	}
+	return byQuery
+}
+
+// fetchTracksCreditedTo fetches every non-missing track credited to any of the given artists as
+// the main artist (role='artist', not albumartist — that avoids tribute/compilation false
+// positives). The non-correlated id IN (subquery) materializes the matching ids once from the
+// media_file_artists(artist_id) covering index, far cheaper than a correlated EXISTS that re-runs
+// per row. That form isn't expressible via the repository's role filters, so the raw squirrel.Expr
+// keeps the media_file_artists schema knowledge here; a dedicated repository method would be the
+// cleaner home if this is reused.
+func (m *Matcher) fetchTracksCreditedTo(ctx context.Context, artistIDs []string) (model.MediaFiles, error) {
+	if len(artistIDs) == 0 {
+		return nil, nil
+	}
+	args := slice.Map(artistIDs, func(id string) any { return id })
+	return m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.And{
+			squirrel.Expr(
+				"media_file.id IN (SELECT media_file_id FROM media_file_artists "+
+					"WHERE role = 'artist' AND artist_id IN ("+squirrel.Placeholders(len(artistIDs))+"))", args...),
+			squirrel.Eq{"missing": false},
+		},
+		Sort: "starred desc, rating desc, year asc, compilation asc",
+	})
 }
 
 // durationProximity returns a score from 0.0 to 1.0 indicating how close the track's duration
@@ -417,6 +493,7 @@ func (m *Matcher) findBestMatch(q songQuery, sanitizedTracks []sanitizedTrack, t
 	bestScore := matchScore{titleSimilarity: -1}
 	found := false
 
+	preferStarred := conf.Server.Matcher.PreferStarred
 	for _, t := range sanitizedTracks {
 		titleSim := similarityRatio(q.title, t.title)
 
@@ -432,7 +509,7 @@ func (m *Matcher) findBestMatch(q songQuery, sanitizedTracks []sanitizedTrack, t
 		score := matchScore{
 			titleSimilarity:   titleSim,
 			durationProximity: durationProximity(q.durationMs, t.mf.Duration),
-			preferredMatch:    conf.Server.Matcher.PreferStarred && isPreferredTrack(t.mf),
+			preferredMatch:    preferStarred && isPreferredTrack(t.mf),
 			albumSimilarity:   albumSim,
 			specificityLevel:  computeSpecificityLevel(q, t, threshold),
 		}
@@ -450,66 +527,34 @@ func isPreferredTrack(mf *model.MediaFile) bool {
 	return mf.Starred || mf.Rating >= 4
 }
 
-// buildTitleQueries converts agent songs into normalized songQuery structs for title+artist matching.
-func (m *Matcher) buildTitleQueries(songs []agents.Song, priorMatches ...map[string]model.MediaFile) []songQuery {
-	var queries []songQuery
-	for _, s := range songs {
-		if songMatchedIn(s, priorMatches...) {
-			continue
-		}
-		queries = append(queries, songQuery{
-			title:      str.SanitizeFieldForSorting(s.Name),
-			artist:     str.SanitizeFieldForSortingNoArticle(s.Artist),
-			artistMBID: s.ArtistMBID,
-			album:      str.SanitizeFieldForSorting(s.Album),
-			albumMBID:  s.AlbumMBID,
-			durationMs: s.Duration,
-		})
-	}
-	return queries
-}
-
-// selectBestMatchingSongs assembles the final result by mapping input songs to their best matching
-// library tracks using priority order: ID > MBID > ISRC > title+artist.
-func (m *Matcher) selectBestMatchingSongs(songs []agents.Song, byID, byMBID, byISRC, byTitleArtist map[string]model.MediaFile, count int) model.MediaFiles {
+// orderAndDedup builds the final ordered result from the per-index matches,
+// applying the count limit and deduplication. A library track is added at most
+// once unless the same input song appears more than once (callers rely on that
+// 1:1 positional behavior for identical duplicate inputs).
+func orderAndDedup(songs []agents.Song, matches map[int]model.MediaFile, count int) model.MediaFiles {
 	mfs := make(model.MediaFiles, 0, len(songs))
-	addedBy := make(map[string]agents.Song, len(songs))
+	addedBy := make(map[string]int, len(songs))
 
-	for _, t := range songs {
+	for i, s := range songs {
 		if len(mfs) == count {
 			break
 		}
-
-		mf, found := findMatchingTrack(t, byID, byMBID, byISRC, byTitleArtist)
+		mf, found := matches[i]
 		if !found {
 			continue
 		}
-
-		if prevSong, alreadyAdded := addedBy[mf.ID]; alreadyAdded {
-			if t != prevSong {
+		if prevIdx, alreadyAdded := addedBy[mf.ID]; alreadyAdded {
+			if s != songs[prevIdx] {
 				continue
 			}
 		} else {
-			addedBy[mf.ID] = t
+			addedBy[mf.ID] = i
 		}
-
 		mfs = append(mfs, mf)
 	}
 	return mfs
 }
 
-// findMatchingTrack looks up a song in the match maps using priority order.
-func findMatchingTrack(t agents.Song, byID, byMBID, byISRC, byTitleArtist map[string]model.MediaFile) (model.MediaFile, bool) {
-	if mf, found := lookupByIdentifiers(t, byID, byMBID, byISRC); found {
-		return mf, true
-	}
-	key := str.SanitizeFieldForSorting(t.Name) + "|" + str.SanitizeFieldForSortingNoArticle(t.Artist)
-	if mf, ok := byTitleArtist[key]; ok {
-		return mf, true
-	}
-	return model.MediaFile{}, false
-}
-
 // similarityRatio calculates the similarity between two strings using Jaro-Winkler algorithm.
 func similarityRatio(a, b string) float64 {
 	if a == b {

core/matcher/matcher_internal_test.go

@@ -1,6 +1,7 @@
 package matcher
 
 import (
+	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -51,3 +52,16 @@ var _ = Describe("similarityRatio", func() {
 		Expect(ratio1).To(Equal(ratio2))
 	})
 })
+
+var _ = Describe("matcher internals", func() {
+	It("computeSpecificityLevel uses sanitizedTrack.artistMBID for artist-MBID levels", func() {
+		q := songQuery{
+			title:      "song",
+			artistMBID: "artist-mbid-1",
+			albumMBID:  "album-mbid-1",
+		}
+		mf := model.MediaFile{Title: "Song", MbzAlbumID: "album-mbid-1"} // note: mf.MbzArtistID intentionally empty
+		t := newSanitizedTrack(&mf, "artist-mbid-1")                     // resolved MBID supplied here
+		Expect(computeSpecificityLevel(q, t, 0.85)).To(Equal(5))
+	})
+})

core/matcher/matcher_test.go

@@ -3,6 +3,7 @@ package matcher_test
 import (
 	"context"
 	"errors"
+	"strings"
 
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
@@ -19,6 +20,7 @@ import (
 var _ = Describe("Matcher", func() {
 	var ds model.DataStore
 	var mediaFileRepo *mockMediaFileRepo
+	var artistRepo *mockArtistRepo
 	var ctx context.Context
 	var m *matcher.Matcher
 
@@ -26,11 +28,13 @@ var _ = Describe("Matcher", func() {
 		ctx = GinkgoT().Context()
 		DeferCleanup(configtest.SetupConfig())
 		mediaFileRepo = newMockMediaFileRepo()
+		artistRepo = newMockArtistRepo()
 		DeferCleanup(func() {
 			mediaFileRepo.AssertExpectations(GinkgoT())
 		})
 		ds = &tests.MockDataStore{
 			MockedMediaFile: mediaFileRepo,
+			MockedArtist:    artistRepo,
 		}
 		m = matcher.New(ds)
 	})
@@ -53,26 +57,49 @@ var _ = Describe("Matcher", func() {
 			Return(matches, nil).Once()
 	}
 
-	// allowOtherPhases installs .Maybe() catch-alls so phases that short-circuit (return
-	// early without hitting the DB) don't cause test failures for unexpected calls. Call
-	// this after expect*Phase for the phases the test actually wants to verify.
-	allowOtherPhases := func() {
+	// allowIdentifierPhases installs .Maybe() catch-alls for the ID/MBID/ISRC phases so
+	// tests that only care about the title phase don't fail on those unexpected calls.
+	allowIdentifierPhases := func() {
 		mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInAnd("media_file.id"))).
 			Return(model.MediaFiles{}, nil).Maybe()
 		mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInAnd("mbz_recording_id"))).
 			Return(model.MediaFiles{}, nil).Maybe()
 		mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInEq("missing"))).
 			Return(model.MediaFiles{}, nil).Maybe()
-		mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInAnd("order_artist_name"))).
+	}
+
+	// allowOtherPhases installs .Maybe() catch-alls so phases that short-circuit (return
+	// early without hitting the DB) don't cause test failures for unexpected calls. Call
+	// this after expect*Phase for the phases the test actually wants to verify.
+	allowOtherPhases := func() {
+		allowIdentifierPhases()
+		artistRepo.On("GetAll", mock.Anything).Return(model.Artists{}, nil).Maybe()
+		mediaFileRepo.On("GetAll", mock.MatchedBy(matchTracksByArtistQuery())).
 			Return(model.MediaFiles{}, nil).Maybe()
 	}
 
-	// setupTitleOnlyExpectations is a convenience for fuzzy-match tests that only exercise
-	// the title+artist phase. The title phase uses .Maybe() because it may short-circuit
-	// when no songs have an artist.
-	setupTitleOnlyExpectations := func(artistTracks model.MediaFiles) {
-		mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInAnd("order_artist_name"))).
-			Return(artistTracks, nil).Maybe()
+	// allowTitlePhase wires title matching from a list of library tracks. Each track must carry
+	// Participants[RoleArtist] with the artist IDs that credit it; the helper derives the artist
+	// rows the artist resolution returns from those participants, then returns the tracks from
+	// the track-fetch query.
+	allowTitlePhase := func(tracks model.MediaFiles) {
+		// Artist resolution: build artist rows from the tracks' participants.
+		seen := map[string]model.Artist{}
+		for _, t := range tracks {
+			for _, p := range t.Participants[model.RoleArtist] {
+				if _, ok := seen[p.ID]; !ok {
+					seen[p.ID] = p.Artist
+				}
+			}
+		}
+		artists := make(model.Artists, 0, len(seen))
+		for _, a := range seen {
+			artists = append(artists, a)
+		}
+		artistRepo.On("GetAll", mock.Anything).Return(artists, nil).Maybe()
+		// Track fetch (media_file_artists subquery).
+		mediaFileRepo.On("GetAll", mock.MatchedBy(matchTracksByArtistQuery())).
+			Return(tracks, nil).Maybe()
 	}
 
 	Describe("MatchSongs", func() {
@@ -140,8 +167,9 @@ var _ = Describe("Matcher", func() {
 				}
 				titleMatch := model.MediaFile{
 					ID: "track-title", Title: "Enjoy the Silence", Artist: "Depeche Mode",
+					Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 				}
-				setupTitleOnlyExpectations(model.MediaFiles{titleMatch})
+				allowTitlePhase(model.MediaFiles{titleMatch})
 				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
@@ -155,8 +183,9 @@ var _ = Describe("Matcher", func() {
 				}
 				fuzzyMatch := model.MediaFile{
 					ID: "track-fuzzy", Title: "Bohemian Rhapsody (Live)", Artist: "Queen",
+					Participants: artistParticipants(model.Artist{ID: "queen", Name: "Queen", OrderArtistName: "queen"}),
 				}
-				setupTitleOnlyExpectations(model.MediaFiles{fuzzyMatch})
+				allowTitlePhase(model.MediaFiles{fuzzyMatch})
 				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
@@ -169,9 +198,11 @@ var _ = Describe("Matcher", func() {
 					{Name: "Yesterday", Artist: "The Beatles"},
 				}
 				differentTracks := model.MediaFiles{
-					{ID: "different", Title: "Tomorrow Never Knows", Artist: "The Beatles"},
+					{ID: "different", Title: "Tomorrow Never Knows", Artist: "The Beatles",
+						Participants: artistParticipants(model.Artist{ID: "beatles", Name: "The Beatles", OrderArtistName: "beatles"}),
+					},
 				}
-				setupTitleOnlyExpectations(differentTracks)
+				allowTitlePhase(differentTracks)
 				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(BeEmpty())
@@ -187,8 +218,9 @@ var _ = Describe("Matcher", func() {
 				}
 				libraryTrack := model.MediaFile{
 					ID: "br-live", Title: "Bohemian Rhapsody (Live)", Artist: "Queen",
+					Participants: artistParticipants(model.Artist{ID: "queen", Name: "Queen", OrderArtistName: "queen"}),
 				}
-				setupTitleOnlyExpectations(model.MediaFiles{libraryTrack})
+				allowTitlePhase(model.MediaFiles{libraryTrack})
 				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
@@ -203,8 +235,9 @@ var _ = Describe("Matcher", func() {
 				}
 				libraryTrack := model.MediaFile{
 					ID: "br", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera",
+					Participants: artistParticipants(model.Artist{ID: "queen", Name: "Queen", OrderArtistName: "queen"}),
 				}
-				setupTitleOnlyExpectations(model.MediaFiles{libraryTrack})
+				allowTitlePhase(model.MediaFiles{libraryTrack})
 				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(2))
@@ -243,11 +276,17 @@ var _ = Describe("Matcher", func() {
 					{Name: "Song C", Artist: "Artist"},
 				}
 				tracks := model.MediaFiles{
-					{ID: "a", Title: "Song A", Artist: "Artist"},
-					{ID: "b", Title: "Song B", Artist: "Artist"},
-					{ID: "c", Title: "Song C", Artist: "Artist"},
+					{ID: "a", Title: "Song A", Artist: "Artist",
+						Participants: artistParticipants(model.Artist{ID: "art", Name: "Artist", OrderArtistName: "artist"}),
+					},
+					{ID: "b", Title: "Song B", Artist: "Artist",
+						Participants: artistParticipants(model.Artist{ID: "art", Name: "Artist", OrderArtistName: "artist"}),
+					},
+					{ID: "c", Title: "Song C", Artist: "Artist",
+						Participants: artistParticipants(model.Artist{ID: "art", Name: "Artist", OrderArtistName: "artist"}),
+					},
 				}
-				setupTitleOnlyExpectations(tracks)
+				allowTitlePhase(tracks)
 				result, err := m.MatchSongs(ctx, songs, 2)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(2))
@@ -261,6 +300,172 @@ var _ = Describe("Matcher", func() {
 				Expect(result).To(BeEmpty())
 			})
 		})
+
+		Context("artist grouping", func() {
+			It("groups title-phase tracks by participant artist ID, not display Artist", func() {
+				songs := []agents.Song{
+					{Name: "Song A", Artist: "Daft Punk"},
+				}
+				// Display Artist differs from the query artist; only the participant
+				// with order_artist_name "daft punk" routes to this query bucket.
+				track := model.MediaFile{
+					ID: "oan-track", Title: "Song A",
+					Artist: "Daft Punk feat. Pharrell",
+					Participants: artistParticipants(
+						model.Artist{ID: "dp", Name: "Daft Punk", OrderArtistName: "daft punk"},
+						model.Artist{ID: "ph", Name: "Pharrell", OrderArtistName: "pharrell"},
+					),
+				}
+				allowTitlePhase(model.MediaFiles{track})
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("oan-track"))
+			})
+
+			It("matches a track that credits the searched artist as a collaborator", func() {
+				songs := []agents.Song{
+					{Name: "Crazy", Artist: "INXS"},
+				}
+				// "Par-T-One vs. INXS" — display Artist is the collaboration, but INXS is a
+				// credited artist participant. Searching INXS must match it.
+				track := model.MediaFile{
+					ID: "collab", Title: "Crazy", Artist: "Par-T-One vs. INXS",
+					Participants: artistParticipants(
+						model.Artist{ID: "a-partone", Name: "Par-T-One", OrderArtistName: "par-t-one"},
+						model.Artist{ID: "a-inxs", Name: "INXS", OrderArtistName: "inxs"},
+					),
+				}
+				allowTitlePhase(model.MediaFiles{track})
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("collab"))
+			})
+
+			It("does not match a track where the searched artist is only the album artist", func() {
+				songs := []agents.Song{
+					{Name: "Qmart", Artist: "808 State"},
+				}
+				// Track performed by Björk on an "808 State" compilation: 808 State is the
+				// albumartist, Björk is the performer. Searching 808 State must NOT match it.
+				track := model.MediaFile{
+					ID: "comp", Title: "Qmart", Artist: "Björk",
+					Participants: model.Participants{
+						model.RoleArtist: model.ParticipantList{
+							{Artist: model.Artist{ID: "a-bjork", Name: "Björk", OrderArtistName: "bjork"}},
+						},
+						model.RoleAlbumArtist: model.ParticipantList{
+							{Artist: model.Artist{ID: "a-808", Name: "808 State", OrderArtistName: "808 state"}},
+						},
+					},
+				}
+				// Artist resolution returns "808 state" only if some artist row matches; here the
+				// album-artist participant exists but is NOT role='artist', so the track-fetch query's
+				// EXISTS (role='artist') would not return the track in production. The mock
+				// returns it anyway; back-mapping must drop it because no role='artist'
+				// participant is a resolved artist for the query "808 state".
+				artistRepo.On("GetAll", mock.Anything).
+					Return(model.Artists{{ID: "a-808", Name: "808 State", OrderArtistName: "808 state"}}, nil).Maybe()
+				mediaFileRepo.On("GetAll", mock.MatchedBy(matchTracksByArtistQuery())).
+					Return(model.MediaFiles{track}, nil).Maybe()
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(BeEmpty())
+			})
+
+			It("resolves the artist by ArtistMBID when the name differs", func() {
+				songs := []agents.Song{
+					{Name: "Song A", Artist: "Typo Artist", ArtistMBID: "mbid-9"},
+				}
+				track := model.MediaFile{
+					ID: "by-mbid", Title: "Song A", Artist: "Correct Artist",
+					Participants: artistParticipants(model.Artist{ID: "a9", Name: "Correct Artist", OrderArtistName: "correct artist", MbzArtistID: "mbid-9"}),
+				}
+				// Artist resolution returns the artist matched by mbz_artist_id; its order name
+				// ("correct artist") differs from the query name ("typo artist"), so
+				// resolution must come from the MBID branch.
+				artistRepo.On("GetAll", mock.Anything).
+					Return(model.Artists{{ID: "a9", Name: "Correct Artist", OrderArtistName: "correct artist", MbzArtistID: "mbid-9"}}, nil).Maybe()
+				mediaFileRepo.On("GetAll", mock.MatchedBy(matchTracksByArtistQuery())).
+					Return(model.MediaFiles{track}, nil).Maybe()
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("by-mbid"))
+			})
+
+			It("resolves both queries when two share one ArtistMBID under different names", func() {
+				// Two agent results for the same MusicBrainz artist but spelled differently
+				// (an alias). Both must match the artist's track via the shared MBID.
+				songs := []agents.Song{
+					{Name: "Song A", Artist: "Alias One", ArtistMBID: "mbid-shared"},
+					{Name: "Song B", Artist: "Alias Two", ArtistMBID: "mbid-shared"},
+				}
+				artist := model.Artist{ID: "a-shared", Name: "Canonical", OrderArtistName: "canonical", MbzArtistID: "mbid-shared"}
+				trackA := model.MediaFile{ID: "ta", Title: "Song A", Artist: "Canonical", Participants: artistParticipants(artist)}
+				trackB := model.MediaFile{ID: "tb", Title: "Song B", Artist: "Canonical", Participants: artistParticipants(artist)}
+				artistRepo.On("GetAll", mock.Anything).
+					Return(model.Artists{{ID: "a-shared", Name: "Canonical", OrderArtistName: "canonical", MbzArtistID: "mbid-shared"}}, nil).Maybe()
+				mediaFileRepo.On("GetAll", mock.MatchedBy(matchTracksByArtistQuery())).
+					Return(model.MediaFiles{trackA, trackB}, nil).Maybe()
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(2))
+				Expect([]string{result[0].ID, result[1].ID}).To(ConsistOf("ta", "tb"))
+			})
+		})
+
+		// These tests register their own track-fetch expectations per-test (to inject
+		// an error), so they use allowIdentifierPhases — NOT allowOtherPhases, which would
+		// add a .Maybe() title-phase catch-all that masks the injected error.
+		Context("title phase DB errors", func() {
+			It("returns an error when the title query fails and nothing else matched", func() {
+				songs := []agents.Song{
+					{Name: "Song A", Artist: "Artist One"},
+					{Name: "Song B", Artist: "Artist Two"},
+				}
+				allowIdentifierPhases()
+				artistRepo.On("GetAll", mock.Anything).Return(model.Artists{
+					{ID: "a1", Name: "Artist One", OrderArtistName: "artist one"},
+					{ID: "a2", Name: "Artist Two", OrderArtistName: "artist two"},
+				}, nil)
+				mediaFileRepo.On("GetAll", mock.MatchedBy(matchTracksByArtistQuery())).
+					Return(nil, errors.New("db down"))
+
+				_, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(ContainSubstring("db down"))
+			})
+
+			It("keeps exact-phase matches when the title query fails", func() {
+				songs := []agents.Song{
+					{ID: "track-1", Name: "Exact Song", Artist: "Exact Artist"},
+					{Name: "Fuzzy Song", Artist: "Fuzzy Artist"},
+				}
+				idMatch := model.MediaFile{ID: "track-1", Title: "Exact Song", Artist: "Exact Artist"}
+				expectIDPhase(model.MediaFiles{idMatch})
+				mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInAnd("mbz_recording_id"))).
+					Return(model.MediaFiles{}, nil).Maybe()
+				mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInEq("missing"))).
+					Return(model.MediaFiles{}, nil).Maybe()
+				artistRepo.On("GetAll", mock.Anything).Return(model.Artists{
+					{ID: "fa", Name: "Fuzzy Artist", OrderArtistName: "fuzzy artist"},
+				}, nil)
+				mediaFileRepo.On("GetAll", mock.MatchedBy(matchTracksByArtistQuery())).
+					Return(nil, errors.New("db down"))
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("track-1"))
+			})
+		})
 	})
 
 	Describe("MatchSongsIndexed", func() {
@@ -319,16 +524,18 @@ var _ = Describe("Matcher", func() {
 			correctMatch := model.MediaFile{
 				ID: "correct-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Violator",
 				MbzArtistID: "artist-mbid-123", MbzAlbumID: "album-mbid-456",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode", MbzArtistID: "artist-mbid-123"}),
 			}
 			wrongMatch := model.MediaFile{
 				ID: "wrong-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Some Other Album",
 				MbzArtistID: "artist-mbid-123", MbzAlbumID: "different-album-mbid",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode", MbzArtistID: "artist-mbid-123"}),
 			}
 			songs := []agents.Song{
 				{Name: "Similar Song", Artist: "Depeche Mode", ArtistMBID: "artist-mbid-123", Album: "Violator", AlbumMBID: "album-mbid-456"},
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+			allowTitlePhase(model.MediaFiles{wrongMatch, correctMatch})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -340,15 +547,17 @@ var _ = Describe("Matcher", func() {
 		It("matches by title + artist name + album name when MBIDs unavailable", func() {
 			correctMatch := model.MediaFile{
 				ID: "correct-match", Title: "Similar Song", Artist: "depeche mode", Album: "violator",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 			wrongMatch := model.MediaFile{
 				ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
+				Participants: artistParticipants(model.Artist{ID: "oa", Name: "Other Artist", OrderArtistName: "other artist"}),
 			}
 			songs := []agents.Song{
 				{Name: "Similar Song", Artist: "Depeche Mode", Album: "Violator"},
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+			allowTitlePhase(model.MediaFiles{wrongMatch, correctMatch})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -360,15 +569,17 @@ var _ = Describe("Matcher", func() {
 		It("matches by title + artist only when album info unavailable", func() {
 			correctMatch := model.MediaFile{
 				ID: "correct-match", Title: "Similar Song", Artist: "depeche mode", Album: "Some Album",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 			wrongMatch := model.MediaFile{
 				ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
+				Participants: artistParticipants(model.Artist{ID: "oa", Name: "Other Artist", OrderArtistName: "other artist"}),
 			}
 			songs := []agents.Song{
 				{Name: "Similar Song", Artist: "Depeche Mode"},
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+			allowTitlePhase(model.MediaFiles{wrongMatch, correctMatch})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -382,7 +593,7 @@ var _ = Describe("Matcher", func() {
 				{Name: "Similar Song"},
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{})
+			allowTitlePhase(model.MediaFiles{})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -391,9 +602,15 @@ var _ = Describe("Matcher", func() {
 		})
 
 		It("returns distinct matches for each artist's version (covers scenario)", func() {
-			cover1 := model.MediaFile{ID: "cover-1", Title: "Yesterday", Artist: "The Beatles", Album: "Help!"}
-			cover2 := model.MediaFile{ID: "cover-2", Title: "Yesterday", Artist: "Ray Charles", Album: "Greatest Hits"}
-			cover3 := model.MediaFile{ID: "cover-3", Title: "Yesterday", Artist: "Frank Sinatra", Album: "My Way"}
+			cover1 := model.MediaFile{ID: "cover-1", Title: "Yesterday", Artist: "The Beatles", Album: "Help!",
+				Participants: artistParticipants(model.Artist{ID: "beatles", Name: "The Beatles", OrderArtistName: "beatles"}),
+			}
+			cover2 := model.MediaFile{ID: "cover-2", Title: "Yesterday", Artist: "Ray Charles", Album: "Greatest Hits",
+				Participants: artistParticipants(model.Artist{ID: "ray-charles", Name: "Ray Charles", OrderArtistName: "ray charles"}),
+			}
+			cover3 := model.MediaFile{ID: "cover-3", Title: "Yesterday", Artist: "Frank Sinatra", Album: "My Way",
+				Participants: artistParticipants(model.Artist{ID: "sinatra", Name: "Frank Sinatra", OrderArtistName: "frank sinatra"}),
+			}
 
 			songs := []agents.Song{
 				{Name: "Yesterday", Artist: "The Beatles", Album: "Help!"},
@@ -401,7 +618,7 @@ var _ = Describe("Matcher", func() {
 				{Name: "Yesterday", Artist: "Frank Sinatra", Album: "My Way"},
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{cover1, cover2, cover3})
+			allowTitlePhase(model.MediaFiles{cover1, cover2, cover3})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -415,13 +632,16 @@ var _ = Describe("Matcher", func() {
 			preciseMatch := model.MediaFile{
 				ID: "precise", Title: "Song A", Artist: "Artist One", Album: "Album One",
 				MbzArtistID: "mbid-1", MbzAlbumID: "album-mbid-1",
+				Participants: artistParticipants(model.Artist{ID: "a1", Name: "Artist One", OrderArtistName: "artist one", MbzArtistID: "mbid-1"}),
 			}
 			lessAccurateMatch := model.MediaFile{
 				ID: "less-accurate", Title: "Song A", Artist: "Artist One", Album: "Compilation",
-				MbzArtistID: "mbid-1",
+				MbzArtistID:  "mbid-1",
+				Participants: artistParticipants(model.Artist{ID: "a1", Name: "Artist One", OrderArtistName: "artist one", MbzArtistID: "mbid-1"}),
 			}
 			artistTwoMatch := model.MediaFile{
 				ID: "artist-two", Title: "Song B", Artist: "Artist Two",
+				Participants: artistParticipants(model.Artist{ID: "a2", Name: "Artist Two", OrderArtistName: "artist two"}),
 			}
 
 			songs := []agents.Song{
@@ -429,7 +649,7 @@ var _ = Describe("Matcher", func() {
 				{Name: "Song B", Artist: "Artist Two"},
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{lessAccurateMatch, preciseMatch, artistTwoMatch})
+			allowTitlePhase(model.MediaFiles{lessAccurateMatch, preciseMatch, artistTwoMatch})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -438,6 +658,31 @@ var _ = Describe("Matcher", func() {
 			Expect(result[0].ID).To(Equal("precise"))
 			Expect(result[1].ID).To(Equal("artist-two"))
 		})
+
+		It("uses the resolved artist MBID for specificity (level 5)", func() {
+			songs := []agents.Song{
+				{Name: "Song A", Artist: "Artist One", ArtistMBID: "mbid-1", Album: "Album One", AlbumMBID: "album-mbid-1"},
+			}
+			// Two tracks with the same title and album; only the one whose resolved artist
+			// carries mbid-1 (and whose album MBID matches) wins via Level 5. Without the
+			// resolved MBID, both tracks tie at Level 3 (name+album) and the first wins by
+			// chance — verifiable by RED-proof: see task-2-report.md.
+			precise := model.MediaFile{
+				ID: "precise", Title: "Song A", Artist: "Artist One", Album: "Album One", MbzAlbumID: "album-mbid-1",
+				Participants: artistParticipants(model.Artist{ID: "a1", Name: "Artist One", OrderArtistName: "artist one", MbzArtistID: "mbid-1"}),
+			}
+			other := model.MediaFile{
+				ID: "other", Title: "Song A", Artist: "Artist One", Album: "Album One", MbzAlbumID: "wrong-album-mbid",
+				Participants: artistParticipants(model.Artist{ID: "a1b", Name: "Artist One", OrderArtistName: "artist one", MbzArtistID: ""}),
+			}
+			// Artist resolution returns both a1 (by name+mbid) and a1b (by name).
+			allowTitlePhase(model.MediaFiles{other, precise})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("precise"))
+		})
 	})
 
 	Describe("fuzzy matching thresholds", func() {
@@ -449,10 +694,12 @@ var _ = Describe("Matcher", func() {
 					{Name: "Paranoid Android", Artist: "Radiohead"},
 				}
 				artistTracks := model.MediaFiles{
-					{ID: "remastered", Title: "Paranoid Android - Remastered", Artist: "Radiohead"},
+					{ID: "remastered", Title: "Paranoid Android - Remastered", Artist: "Radiohead",
+						Participants: artistParticipants(model.Artist{ID: "rh", Name: "Radiohead", OrderArtistName: "radiohead"}),
+					},
 				}
 
-				setupTitleOnlyExpectations(artistTracks)
+				allowTitlePhase(artistTracks)
 
 				result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -468,10 +715,12 @@ var _ = Describe("Matcher", func() {
 					{Name: "Bohemian Rhapsody", Artist: "Queen"},
 				}
 				artistTracks := model.MediaFiles{
-					{ID: "live", Title: "Bohemian Rhapsody (Live)", Artist: "Queen"},
+					{ID: "live", Title: "Bohemian Rhapsody (Live)", Artist: "Queen",
+						Participants: artistParticipants(model.Artist{ID: "queen", Name: "Queen", OrderArtistName: "queen"}),
+					},
 				}
 
-				setupTitleOnlyExpectations(artistTracks)
+				allowTitlePhase(artistTracks)
 
 				result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -489,10 +738,12 @@ var _ = Describe("Matcher", func() {
 					{Name: "Paranoid Android", Artist: "Radiohead"},
 				}
 				artistTracks := model.MediaFiles{
-					{ID: "remastered", Title: "Paranoid Android - Remastered", Artist: "Radiohead"},
+					{ID: "remastered", Title: "Paranoid Android - Remastered", Artist: "Radiohead",
+						Participants: artistParticipants(model.Artist{ID: "rh", Name: "Radiohead", OrderArtistName: "radiohead"}),
+					},
 				}
 
-				setupTitleOnlyExpectations(artistTracks)
+				allowTitlePhase(artistTracks)
 
 				result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -509,10 +760,12 @@ var _ = Describe("Matcher", func() {
 					{Name: "Song", Artist: "Artist"},
 				}
 				artistTracks := model.MediaFiles{
-					{ID: "extended", Title: "Song (Extended Mix)", Artist: "Artist"},
+					{ID: "extended", Title: "Song (Extended Mix)", Artist: "Artist",
+						Participants: artistParticipants(model.Artist{ID: "art", Name: "Artist", OrderArtistName: "artist"}),
+					},
 				}
 
-				setupTitleOnlyExpectations(artistTracks)
+				allowTitlePhase(artistTracks)
 
 				result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -535,12 +788,14 @@ var _ = Describe("Matcher", func() {
 			}
 			correctMatch := model.MediaFile{
 				ID: "correct", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera (2011 Remaster)",
+				Participants: artistParticipants(model.Artist{ID: "queen", Name: "Queen", OrderArtistName: "queen"}),
 			}
 			wrongMatch := model.MediaFile{
 				ID: "wrong", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "Greatest Hits",
+				Participants: artistParticipants(model.Artist{ID: "queen", Name: "Queen", OrderArtistName: "queen"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+			allowTitlePhase(model.MediaFiles{wrongMatch, correctMatch})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -555,12 +810,14 @@ var _ = Describe("Matcher", func() {
 			}
 			correctMatch := model.MediaFile{
 				ID: "correct", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator (Deluxe Edition)",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 			wrongMatch := model.MediaFile{
 				ID: "wrong", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "101",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+			allowTitlePhase(model.MediaFiles{wrongMatch, correctMatch})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -575,12 +832,14 @@ var _ = Describe("Matcher", func() {
 			}
 			exactMatch := model.MediaFile{
 				ID: "exact", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 			fuzzyMatch := model.MediaFile{
 				ID: "fuzzy", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator (Deluxe Edition)",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{fuzzyMatch, exactMatch})
+			allowTitlePhase(model.MediaFiles{fuzzyMatch, exactMatch})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -596,12 +855,15 @@ var _ = Describe("Matcher", func() {
 			}
 			albumMatch := model.MediaFile{
 				ID: "album-match", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 			starredTrack := model.MediaFile{
-				ID: "starred", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles", Annotations: model.Annotations{Starred: true},
+				ID: "starred", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles",
+				Annotations:  model.Annotations{Starred: true},
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{albumMatch, starredTrack})
+			allowTitlePhase(model.MediaFiles{albumMatch, starredTrack})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -617,12 +879,15 @@ var _ = Describe("Matcher", func() {
 			}
 			albumMatch := model.MediaFile{
 				ID: "album-match", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator",
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 			ratedTrack := model.MediaFile{
-				ID: "rated", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles", Annotations: model.Annotations{Rating: 4},
+				ID: "rated", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles",
+				Annotations:  model.Annotations{Rating: 4},
+				Participants: artistParticipants(model.Artist{ID: "dm", Name: "Depeche Mode", OrderArtistName: "depeche mode"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{albumMatch, ratedTrack})
+			allowTitlePhase(model.MediaFiles{albumMatch, ratedTrack})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -643,12 +908,14 @@ var _ = Describe("Matcher", func() {
 			}
 			correctMatch := model.MediaFile{
 				ID: "correct", Title: "Similar Song", Artist: "Test Artist", Duration: 180.0,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 			wrongDuration := model.MediaFile{
 				ID: "wrong", Title: "Similar Song", Artist: "Test Artist", Duration: 240.0,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{wrongDuration, correctMatch})
+			allowTitlePhase(model.MediaFiles{wrongDuration, correctMatch})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -663,9 +930,10 @@ var _ = Describe("Matcher", func() {
 			}
 			closeDuration := model.MediaFile{
 				ID: "close-duration", Title: "Similar Song", Artist: "Test Artist", Duration: 182.5,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{closeDuration})
+			allowTitlePhase(model.MediaFiles{closeDuration})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -680,12 +948,14 @@ var _ = Describe("Matcher", func() {
 			}
 			closeDuration := model.MediaFile{
 				ID: "close", Title: "Similar Song", Artist: "Test Artist", Duration: 181.0,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 			farDuration := model.MediaFile{
 				ID: "far", Title: "Similar Song", Artist: "Test Artist", Duration: 190.0,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{farDuration, closeDuration})
+			allowTitlePhase(model.MediaFiles{farDuration, closeDuration})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -700,9 +970,10 @@ var _ = Describe("Matcher", func() {
 			}
 			differentDuration := model.MediaFile{
 				ID: "different", Title: "Similar Song", Artist: "Test Artist", Duration: 300.0,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{differentDuration})
+			allowTitlePhase(model.MediaFiles{differentDuration})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -717,12 +988,14 @@ var _ = Describe("Matcher", func() {
 			}
 			differentTitle := model.MediaFile{
 				ID: "wrong-title", Title: "Different Song", Artist: "Test Artist", Duration: 180.0,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 			correctTitle := model.MediaFile{
 				ID: "correct-title", Title: "Similar Song", Artist: "Test Artist", Duration: 300.0,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{differentTitle, correctTitle})
+			allowTitlePhase(model.MediaFiles{differentTitle, correctTitle})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -737,9 +1010,10 @@ var _ = Describe("Matcher", func() {
 			}
 			anyTrack := model.MediaFile{
 				ID: "any", Title: "Similar Song", Artist: "Test Artist", Duration: 999.0,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{anyTrack})
+			allowTitlePhase(model.MediaFiles{anyTrack})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -754,9 +1028,10 @@ var _ = Describe("Matcher", func() {
 			}
 			shortTrack := model.MediaFile{
 				ID: "short", Title: "Short Song", Artist: "Test Artist", Duration: 31.0,
+				Participants: artistParticipants(model.Artist{ID: "ta", Name: "Test Artist", OrderArtistName: "test artist"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{shortTrack})
+			allowTitlePhase(model.MediaFiles{shortTrack})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -764,6 +1039,30 @@ var _ = Describe("Matcher", func() {
 			Expect(result).To(HaveLen(1))
 			Expect(result[0].ID).To(Equal("short"))
 		})
+
+		It("matches same title+artist songs to their own closest-duration track", func() {
+			songs := []agents.Song{
+				{Name: "Same Song", Artist: "Same Artist", Duration: 180000},
+				{Name: "Same Song", Artist: "Same Artist", Duration: 240000},
+			}
+			shortTrack := model.MediaFile{
+				ID: "short", Title: "Same Song", Artist: "Same Artist", Duration: 180.0,
+				Participants: artistParticipants(model.Artist{ID: "sa", Name: "Same Artist", OrderArtistName: "same artist"}),
+			}
+			longTrack := model.MediaFile{
+				ID: "long", Title: "Same Song", Artist: "Same Artist", Duration: 240.0,
+				Participants: artistParticipants(model.Artist{ID: "sa", Name: "Same Artist", OrderArtistName: "same artist"}),
+			}
+
+			allowTitlePhase(model.MediaFiles{shortTrack, longTrack})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(2))
+			Expect(result[0].ID).To(Equal("short"))
+			Expect(result[1].ID).To(Equal("long"))
+		})
 	})
 
 	Describe("deduplication edge cases", func() {
@@ -780,9 +1079,10 @@ var _ = Describe("Matcher", func() {
 			}
 			libraryTrack := model.MediaFile{
 				ID: "yesterday", Title: "Yesterday", Artist: "The Beatles", Album: "Help!",
+				Participants: artistParticipants(model.Artist{ID: "beatles", Name: "The Beatles", OrderArtistName: "beatles"}),
 			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{libraryTrack})
+			allowTitlePhase(model.MediaFiles{libraryTrack})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -798,11 +1098,17 @@ var _ = Describe("Matcher", func() {
 				{Name: "Song B", Artist: "Artist"},
 				{Name: "Song C", Artist: "Artist"},
 			}
-			trackA := model.MediaFile{ID: "track-a", Title: "Song A", Artist: "Artist"}
-			trackB := model.MediaFile{ID: "track-b", Title: "Song B", Artist: "Artist"}
-			trackC := model.MediaFile{ID: "track-c", Title: "Song C", Artist: "Artist"}
+			trackA := model.MediaFile{ID: "track-a", Title: "Song A", Artist: "Artist",
+				Participants: artistParticipants(model.Artist{ID: "art", Name: "Artist", OrderArtistName: "artist"}),
+			}
+			trackB := model.MediaFile{ID: "track-b", Title: "Song B", Artist: "Artist",
+				Participants: artistParticipants(model.Artist{ID: "art", Name: "Artist", OrderArtistName: "artist"}),
+			}
+			trackC := model.MediaFile{ID: "track-c", Title: "Song C", Artist: "Artist",
+				Participants: artistParticipants(model.Artist{ID: "art", Name: "Artist", OrderArtistName: "artist"}),
+			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{trackA, trackB, trackC})
+			allowTitlePhase(model.MediaFiles{trackA, trackB, trackC})
 
 			result, err := m.MatchSongs(ctx, songs, 5)
 
@@ -820,10 +1126,14 @@ var _ = Describe("Matcher", func() {
 				{Name: "Song B", Artist: "Artist"},
 				{Name: "Song B (Remix)", Artist: "Artist"},
 			}
-			trackA := model.MediaFile{ID: "track-a", Title: "Song A", Artist: "Artist"}
-			trackB := model.MediaFile{ID: "track-b", Title: "Song B", Artist: "Artist"}
+			trackA := model.MediaFile{ID: "track-a", Title: "Song A", Artist: "Artist",
+				Participants: artistParticipants(model.Artist{ID: "art", Name: "Artist", OrderArtistName: "artist"}),
+			}
+			trackB := model.MediaFile{ID: "track-b", Title: "Song B", Artist: "Artist",
+				Participants: artistParticipants(model.Artist{ID: "art", Name: "Artist", OrderArtistName: "artist"}),
+			}
 
-			setupTitleOnlyExpectations(model.MediaFiles{trackA, trackB})
+			allowTitlePhase(model.MediaFiles{trackA, trackB})
 
 			result, err := m.MatchSongs(ctx, songs, 2)
 
@@ -866,6 +1176,27 @@ func (m *mockMediaFileRepo) SetError(hasError bool) {
 	}
 }
 
+type mockArtistRepo struct {
+	mock.Mock
+	model.ArtistRepository
+}
+
+func newMockArtistRepo() *mockArtistRepo {
+	return &mockArtistRepo{}
+}
+
+func (m *mockArtistRepo) GetAll(options ...model.QueryOptions) (model.Artists, error) {
+	argsSlice := make([]any, len(options))
+	for i, v := range options {
+		argsSlice[i] = v
+	}
+	args := m.Called(argsSlice...)
+	if args.Get(0) == nil {
+		return nil, args.Error(1)
+	}
+	return args.Get(0).(model.Artists), args.Error(1)
+}
+
 // matchFieldInAnd returns a matcher that checks whether QueryOptions.Filters is a
 // squirrel.And whose first element is a squirrel.Eq containing the given field name.
 func matchFieldInAnd(fieldName string) func(opt model.QueryOptions) bool {
@@ -895,3 +1226,30 @@ func matchFieldInEq(fieldName string) func(opt model.QueryOptions) bool {
 		return hasField
 	}
 }
+
+// artistParticipants builds a Participants map crediting the given artists under RoleArtist.
+func artistParticipants(artists ...model.Artist) model.Participants {
+	list := make(model.ParticipantList, len(artists))
+	for i, a := range artists {
+		list[i] = model.Participant{Artist: a}
+	}
+	return model.Participants{model.RoleArtist: list}
+}
+
+// matchTracksByArtistQuery matches the title phase's track-fetch query, identified by its
+// squirrel.And containing a squirrel.Expr whose SQL references media_file_artists.
+func matchTracksByArtistQuery() func(opt model.QueryOptions) bool {
+	return func(opt model.QueryOptions) bool {
+		and, ok := opt.Filters.(squirrel.And)
+		if !ok {
+			return false
+		}
+		for _, f := range and {
+			sql, _, err := f.ToSql()
+			if err == nil && strings.Contains(sql, "media_file_artists") {
+				return true
+			}
+		}
+		return false
+	}
+}

core/stream/legacy_client.go

@@ -12,7 +12,7 @@ import (
 
 // buildLegacyClientInfo translates legacy Subsonic stream/download parameters
 // into a ClientInfo for use with MakeDecision.
-func buildLegacyClientInfo(mf *model.MediaFile, reqFormat string, reqBitRate int) *ClientInfo {
+func buildLegacyClientInfo(mf *model.MediaFile, reqFormat string, reqBitRate int, playerMaxBitRate int) *ClientInfo {
 	ci := &ClientInfo{Name: "legacy"}
 
 	// Determine target format for transcoding
@@ -22,6 +22,10 @@ func buildLegacyClientInfo(mf *model.MediaFile, reqFormat string, reqBitRate int
 		targetFormat = reqFormat
 	case reqBitRate > 0 && reqBitRate < mf.BitRate && conf.Server.DefaultDownsamplingFormat != "":
 		targetFormat = conf.Server.DefaultDownsamplingFormat
+	case playerMaxBitRate > 0 && playerMaxBitRate < mf.BitRate && conf.Server.DefaultDownsamplingFormat != "":
+		// Server-side player MaxBitRate alone forces downsampling, even when the
+		// client sent no format/bitrate params (issue #5583, legacy /stream path).
+		targetFormat = conf.Server.DefaultDownsamplingFormat
 	}
 
 	if targetFormat != "" {
@@ -63,15 +67,19 @@ func (s *deciderService) ResolveRequest(ctx context.Context, mf *model.MediaFile
 		return req
 	}
 
-	clientInfo := buildLegacyClientInfo(mf, reqFormat, reqBitRate)
+	playerMaxBitRate := 0
+	if player, ok := request.PlayerFrom(ctx); ok {
+		playerMaxBitRate = player.MaxBitRate
+	}
+
+	clientInfo := buildLegacyClientInfo(mf, reqFormat, reqBitRate, playerMaxBitRate)
 
 	// Apply server-side player transcoding override before making the decision
 	if trc, ok := request.TranscodingFrom(ctx); ok && trc.TargetFormat != "" {
 		clientInfo = applyServerOverride(ctx, clientInfo, &trc)
-	} else if player, ok := request.PlayerFrom(ctx); ok && player.MaxBitRate > 0 {
-		if clientInfo.MaxAudioBitrate == 0 || player.MaxBitRate < clientInfo.MaxAudioBitrate {
-			modified := *clientInfo
-			modified.MaxAudioBitrate = player.MaxBitRate
+	} else if player, ok := request.PlayerFrom(ctx); ok {
+		modified := *clientInfo
+		if modified.CapBitrate(player.MaxBitRate) {
 			clientInfo = &modified
 			log.Debug(ctx, "Applied player MaxBitRate cap", "playerMaxBitRate", player.MaxBitRate, "client", clientInfo.Name)
 		}

core/stream/legacy_client_test.go

@@ -21,7 +21,7 @@ var _ = Describe("buildLegacyClientInfo", func() {
 	})
 
 	It("sets transcoding profile for explicit format without bitrate", func() {
-		ci := buildLegacyClientInfo(mf, "mp3", 0)
+		ci := buildLegacyClientInfo(mf, "mp3", 0, 0)
 
 		Expect(ci.Name).To(Equal("legacy"))
 		Expect(ci.TranscodingProfiles).To(HaveLen(1))
@@ -34,7 +34,7 @@ var _ = Describe("buildLegacyClientInfo", func() {
 	})
 
 	It("does not add direct play profile when explicit format differs from source (no bitrate)", func() {
-		ci := buildLegacyClientInfo(mf, "opus", 0)
+		ci := buildLegacyClientInfo(mf, "opus", 0, 0)
 
 		Expect(ci.TranscodingProfiles).To(HaveLen(1))
 		Expect(ci.TranscodingProfiles[0].Container).To(Equal("opus"))
@@ -42,7 +42,7 @@ var _ = Describe("buildLegacyClientInfo", func() {
 	})
 
 	It("adds direct play profile when explicit format matches source format", func() {
-		ci := buildLegacyClientInfo(mf, "flac", 0)
+		ci := buildLegacyClientInfo(mf, "flac", 0, 0)
 
 		Expect(ci.TranscodingProfiles).To(HaveLen(1))
 		Expect(ci.TranscodingProfiles[0].Container).To(Equal("flac"))
@@ -52,7 +52,7 @@ var _ = Describe("buildLegacyClientInfo", func() {
 	})
 
 	It("sets transcoding profile and bitrate for explicit format with bitrate", func() {
-		ci := buildLegacyClientInfo(mf, "mp3", 192)
+		ci := buildLegacyClientInfo(mf, "mp3", 192, 0)
 
 		Expect(ci.TranscodingProfiles).To(HaveLen(1))
 		Expect(ci.TranscodingProfiles[0].Container).To(Equal("mp3"))
@@ -63,7 +63,7 @@ var _ = Describe("buildLegacyClientInfo", func() {
 	})
 
 	It("returns direct play profile when no format and no bitrate", func() {
-		ci := buildLegacyClientInfo(mf, "", 0)
+		ci := buildLegacyClientInfo(mf, "", 0, 0)
 
 		Expect(ci.DirectPlayProfiles).To(HaveLen(1))
 		Expect(ci.DirectPlayProfiles[0].Containers).To(BeEmpty())
@@ -77,7 +77,7 @@ var _ = Describe("buildLegacyClientInfo", func() {
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.DefaultDownsamplingFormat = "opus"
 
-		ci := buildLegacyClientInfo(mf, "", 128)
+		ci := buildLegacyClientInfo(mf, "", 128, 0)
 
 		Expect(ci.TranscodingProfiles).To(HaveLen(1))
 		Expect(ci.TranscodingProfiles[0].Container).To(Equal("opus"))
@@ -91,7 +91,7 @@ var _ = Describe("buildLegacyClientInfo", func() {
 	})
 
 	It("returns direct play when bitrate >= source bitrate", func() {
-		ci := buildLegacyClientInfo(mf, "", 960)
+		ci := buildLegacyClientInfo(mf, "", 960, 0)
 
 		Expect(ci.DirectPlayProfiles).To(HaveLen(1))
 		Expect(ci.DirectPlayProfiles[0].Containers).To(BeEmpty())
@@ -100,6 +100,51 @@ var _ = Describe("buildLegacyClientInfo", func() {
 		Expect(ci.TranscodingProfiles).To(BeEmpty())
 		Expect(ci.MaxAudioBitrate).To(BeZero())
 	})
+
+	It("uses default downsampling format when player MaxBitRate is below source and no format/bitrate", func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DefaultDownsamplingFormat = "opus"
+
+		ci := buildLegacyClientInfo(mf, "", 0, 256)
+
+		Expect(ci.TranscodingProfiles).To(HaveLen(1))
+		Expect(ci.TranscodingProfiles[0].Container).To(Equal("opus"))
+		Expect(ci.TranscodingProfiles[0].AudioCodec).To(Equal("opus"))
+		Expect(ci.DirectPlayProfiles).To(HaveLen(1))
+		Expect(ci.DirectPlayProfiles[0].Containers).To(Equal([]string{"flac"}))
+	})
+
+	It("does not downsample when player MaxBitRate is >= source bitrate", func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DefaultDownsamplingFormat = "opus"
+
+		ci := buildLegacyClientInfo(mf, "", 0, 960)
+
+		Expect(ci.TranscodingProfiles).To(BeEmpty())
+		Expect(ci.DirectPlayProfiles).To(HaveLen(1))
+		Expect(ci.DirectPlayProfiles[0].Containers).To(BeEmpty())
+	})
+
+	It("does not downsample when DefaultDownsamplingFormat is empty even with player cap", func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DefaultDownsamplingFormat = ""
+
+		ci := buildLegacyClientInfo(mf, "", 0, 256)
+
+		Expect(ci.TranscodingProfiles).To(BeEmpty())
+		Expect(ci.DirectPlayProfiles).To(HaveLen(1))
+		Expect(ci.DirectPlayProfiles[0].Containers).To(BeEmpty())
+	})
+
+	It("prefers explicit request format over player cap", func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DefaultDownsamplingFormat = "opus"
+
+		ci := buildLegacyClientInfo(mf, "mp3", 0, 256)
+
+		Expect(ci.TranscodingProfiles).To(HaveLen(1))
+		Expect(ci.TranscodingProfiles[0].Container).To(Equal("mp3"))
+	})
 })
 
 var _ = Describe("ResolveRequest", func() {
@@ -289,6 +334,33 @@ var _ = Describe("ResolveRequest", func() {
 
 			Expect(req.Format).To(Equal("raw"))
 		})
+
+		It("downsamples using DefaultDownsamplingFormat when only player MaxBitRate is set (no format/bitrate)", func() {
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.DefaultDownsamplingFormat = "opus"
+
+			mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 2, SampleRate: 44100, BitDepth: new(16)})
+			playerCtx := request.WithPlayer(ctx, model.Player{MaxBitRate: 256})
+
+			decider := svc.(*deciderService)
+			req := decider.ResolveRequest(playerCtx, mf, "", 0, 0)
+
+			Expect(req.Format).To(Equal("opus"))
+			Expect(req.BitRate).To(Equal(256))
+		})
+
+		It("serves raw when only player MaxBitRate is set but no DefaultDownsamplingFormat", func() {
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.DefaultDownsamplingFormat = ""
+
+			mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 2, SampleRate: 44100, BitDepth: new(16)})
+			playerCtx := request.WithPlayer(ctx, model.Player{MaxBitRate: 256})
+
+			decider := svc.(*deciderService)
+			req := decider.ResolveRequest(playerCtx, mf, "", 0, 0)
+
+			Expect(req.Format).To(Equal("raw"))
+		})
 	})
 
 	Context("fallback for unknown format", func() {

core/stream/types.go

@@ -40,6 +40,50 @@ type ClientInfo struct {
 	CodecProfiles              []CodecProfile
 }
 
+// CapBitrate lowers the client's declared audio bitrate limits to maxKbps,
+// never raising them. A zero limit means "unlimited" and is set to maxKbps.
+// Returns true if anything changed. No-op when maxKbps <= 0.
+func (ci *ClientInfo) CapBitrate(maxKbps int) bool {
+	if maxKbps <= 0 {
+		return false
+	}
+	changed := false
+	if ci.MaxAudioBitrate == 0 || maxKbps < ci.MaxAudioBitrate {
+		ci.MaxAudioBitrate = maxKbps
+		changed = true
+	}
+	if ci.MaxTranscodingAudioBitrate == 0 || maxKbps < ci.MaxTranscodingAudioBitrate {
+		ci.MaxTranscodingAudioBitrate = maxKbps
+		changed = true
+	}
+	return changed
+}
+
+// ForceFormat narrows the client to transcoding to targetFormat and suppresses
+// direct play, but only if the client already declares a profile for that
+// format. All matching profiles are kept so negotiation can still pick among
+// them (e.g. by protocol). Returns false (no-op) when targetFormat is empty or
+// unsupported.
+func (ci *ClientInfo) ForceFormat(targetFormat string) bool {
+	if targetFormat == "" {
+		return false
+	}
+	var matched []Profile
+	for i := range ci.TranscodingProfiles {
+		// matchesContainer is alias-aware, so a forced "oga" (legacy Opus
+		// target_format) still matches a resolved "opus" profile.
+		if _, format := resolveTargetFormat(&ci.TranscodingProfiles[i]); matchesContainer(format, []string{targetFormat}) {
+			matched = append(matched, ci.TranscodingProfiles[i])
+		}
+	}
+	if len(matched) == 0 {
+		return false
+	}
+	ci.TranscodingProfiles = matched
+	ci.DirectPlayProfiles = nil
+	return true
+}
+
 // DirectPlayProfile describes a format the client can play directly
 type DirectPlayProfile struct {
 	Containers       []string

core/stream/types_test.go

@@ -0,0 +1,133 @@
+package stream
+
+import (
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("ClientInfo", func() {
+	Describe("CapBitrate", func() {
+		It("is a no-op when maxKbps is zero", func() {
+			ci := &ClientInfo{MaxAudioBitrate: 320, MaxTranscodingAudioBitrate: 320}
+			Expect(ci.CapBitrate(0)).To(BeFalse())
+			Expect(ci.MaxAudioBitrate).To(Equal(320))
+			Expect(ci.MaxTranscodingAudioBitrate).To(Equal(320))
+		})
+
+		It("is a no-op when maxKbps is negative", func() {
+			ci := &ClientInfo{MaxAudioBitrate: 320, MaxTranscodingAudioBitrate: 320}
+			Expect(ci.CapBitrate(-1)).To(BeFalse())
+			Expect(ci.MaxAudioBitrate).To(Equal(320))
+			Expect(ci.MaxTranscodingAudioBitrate).To(Equal(320))
+		})
+
+		It("sets both limits when both are zero (unlimited)", func() {
+			ci := &ClientInfo{}
+			Expect(ci.CapBitrate(256)).To(BeTrue())
+			Expect(ci.MaxAudioBitrate).To(Equal(256))
+			Expect(ci.MaxTranscodingAudioBitrate).To(Equal(256))
+		})
+
+		It("lowers limits higher than maxKbps", func() {
+			ci := &ClientInfo{MaxAudioBitrate: 320, MaxTranscodingAudioBitrate: 500}
+			Expect(ci.CapBitrate(192)).To(BeTrue())
+			Expect(ci.MaxAudioBitrate).To(Equal(192))
+			Expect(ci.MaxTranscodingAudioBitrate).To(Equal(192))
+		})
+
+		It("does not raise limits lower than maxKbps", func() {
+			ci := &ClientInfo{MaxAudioBitrate: 128, MaxTranscodingAudioBitrate: 96}
+			Expect(ci.CapBitrate(320)).To(BeFalse())
+			Expect(ci.MaxAudioBitrate).To(Equal(128))
+			Expect(ci.MaxTranscodingAudioBitrate).To(Equal(96))
+		})
+
+		It("reports changed when only one limit is lowered", func() {
+			ci := &ClientInfo{MaxAudioBitrate: 320, MaxTranscodingAudioBitrate: 128}
+			Expect(ci.CapBitrate(192)).To(BeTrue())
+			Expect(ci.MaxAudioBitrate).To(Equal(192))
+			Expect(ci.MaxTranscodingAudioBitrate).To(Equal(128))
+		})
+
+		It("caps only the zero (unlimited) limit", func() {
+			ci := &ClientInfo{MaxAudioBitrate: 128, MaxTranscodingAudioBitrate: 0}
+			Expect(ci.CapBitrate(192)).To(BeTrue())
+			Expect(ci.MaxAudioBitrate).To(Equal(128))
+			Expect(ci.MaxTranscodingAudioBitrate).To(Equal(192))
+		})
+	})
+
+	Describe("ForceFormat", func() {
+		It("restricts to the forced format and clears direct play when supported", func() {
+			ci := &ClientInfo{
+				DirectPlayProfiles: []DirectPlayProfile{{Containers: []string{"flac"}, AudioCodecs: []string{"flac"}}},
+				TranscodingProfiles: []Profile{
+					{Container: "flac", AudioCodec: "flac", Protocol: ProtocolHTTP},
+					{Container: "ogg", AudioCodec: "opus", Protocol: ProtocolHTTP},
+					{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP},
+				},
+			}
+			ok := ci.ForceFormat("opus")
+			Expect(ok).To(BeTrue())
+			Expect(ci.TranscodingProfiles).To(HaveLen(1))
+			Expect(ci.TranscodingProfiles[0].AudioCodec).To(Equal("opus"))
+			Expect(ci.DirectPlayProfiles).To(BeEmpty())
+		})
+
+		It("matches a container-only forced format (mp3)", func() {
+			ci := &ClientInfo{
+				TranscodingProfiles: []Profile{
+					{Container: "ogg", AudioCodec: "opus", Protocol: ProtocolHTTP},
+					{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP},
+				},
+			}
+			ok := ci.ForceFormat("mp3")
+			Expect(ok).To(BeTrue())
+			Expect(ci.TranscodingProfiles).To(HaveLen(1))
+			Expect(ci.TranscodingProfiles[0].Container).To(Equal("mp3"))
+		})
+
+		It("matches the forced format against codec aliases (oga/opus)", func() {
+			ci := &ClientInfo{
+				TranscodingProfiles: []Profile{
+					{Container: "ogg", AudioCodec: "opus", Protocol: ProtocolHTTP},
+					{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP},
+				},
+			}
+			// Legacy DBs may store the Opus transcoding as target_format "oga".
+			ok := ci.ForceFormat("oga")
+			Expect(ok).To(BeTrue())
+			Expect(ci.TranscodingProfiles).To(HaveLen(1))
+			Expect(ci.TranscodingProfiles[0].AudioCodec).To(Equal("opus"))
+		})
+
+		It("is a no-op when the forced format is not supported by the client", func() {
+			original := []Profile{{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP}}
+			ci := &ClientInfo{
+				DirectPlayProfiles:  []DirectPlayProfile{{Containers: []string{"flac"}}},
+				TranscodingProfiles: original,
+			}
+			ok := ci.ForceFormat("opus")
+			Expect(ok).To(BeFalse())
+			Expect(ci.TranscodingProfiles).To(Equal(original))
+			Expect(ci.DirectPlayProfiles).To(HaveLen(1))
+		})
+
+		It("is a no-op for an empty target format", func() {
+			ci := &ClientInfo{TranscodingProfiles: []Profile{{Container: "mp3", AudioCodec: "mp3"}}}
+			Expect(ci.ForceFormat("")).To(BeFalse())
+		})
+
+		It("keeps all matching profiles when multiple resolve to the forced format", func() {
+			first := Profile{Container: "ogg", AudioCodec: "opus", Protocol: ProtocolHTTP}
+			second := Profile{Container: "ogg", AudioCodec: "opus", Protocol: ProtocolHTTP, MaxAudioChannels: 2}
+			other := Profile{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP}
+			ci := &ClientInfo{TranscodingProfiles: []Profile{first, other, second}}
+
+			ok := ci.ForceFormat("opus")
+
+			Expect(ok).To(BeTrue())
+			Expect(ci.TranscodingProfiles).To(ConsistOf(first, second))
+		})
+	})
+})

db/migrations/20200130083147_create_schema.go

@@ -12,9 +12,9 @@ func init() {
 	goose.AddMigrationContext(Up20200130083147, Down20200130083147)
 }
 
-func Up20200130083147(_ context.Context, tx *sql.Tx) error {
+func Up20200130083147(ctx context.Context, tx *sql.Tx) error {
 	log.Info("Creating DB Schema")
-	_, err := tx.Exec(`
+	_, err := tx.ExecContext(ctx, `
 create table if not exists album
 (
 	id varchar(255) not null
@@ -179,6 +179,6 @@ create table if not exists user
 	return err
 }
 
-func Down20200130083147(_ context.Context, tx *sql.Tx) error {
+func Down20200130083147(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200131183653_standardize_item_type.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20200131183653, Down20200131183653)
 }
 
-func Up20200131183653(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200131183653(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table search_dg_tmp
 (
 	id varchar(255) not null
@@ -37,8 +37,8 @@ update annotation set item_type = 'media_file' where item_type = 'mediaFile';
 	return err
 }
 
-func Down20200131183653(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Down20200131183653(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table search_dg_tmp
 (
 	id varchar(255) not null

db/migrations/20200208222418_add_defaults_to_annotations.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20200208222418, Down20200208222418)
 }
 
-func Up20200208222418(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200208222418(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 update annotation set play_count = 0 where play_count is null;
 update annotation set rating = 0 where rating is null;
 create table annotation_dg_tmp
@@ -51,6 +51,6 @@ create index annotation_starred
 	return err
 }
 
-func Down20200208222418(_ context.Context, tx *sql.Tx) error {
+func Down20200208222418(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200220143731_change_duration_to_float.go

@@ -11,9 +11,9 @@ func init() {
 	goose.AddMigrationContext(Up20200220143731, Down20200220143731)
 }
 
-func Up20200220143731(_ context.Context, tx *sql.Tx) error {
-	notice(tx, "This migration will force the next scan to be a full rescan!")
-	_, err := tx.Exec(`
+func Up20200220143731(ctx context.Context, tx *sql.Tx) error {
+	notice(ctx, tx, "This migration will force the next scan to be a full rescan!")
+	_, err := tx.ExecContext(ctx, `
 create table media_file_dg_tmp
 (
 	id varchar(255) not null
@@ -125,6 +125,6 @@ update media_file set updated_at = '0001-01-01';
 	return err
 }
 
-func Down20200220143731(_ context.Context, tx *sql.Tx) error {
+func Down20200220143731(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200310171621_enable_search_by_albumartist.go

@@ -11,11 +11,11 @@ func init() {
 	goose.AddMigrationContext(Up20200310171621, Down20200310171621)
 }
 
-func Up20200310171621(_ context.Context, tx *sql.Tx) error {
-	notice(tx, "A full rescan will be performed to enable search by Album Artist!")
-	return forceFullRescan(tx)
+func Up20200310171621(ctx context.Context, tx *sql.Tx) error {
+	notice(ctx, tx, "A full rescan will be performed to enable search by Album Artist!")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200310171621(_ context.Context, tx *sql.Tx) error {
+func Down20200310171621(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200310181627_add_transcoding_and_player_tables.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20200310181627, Down20200310181627)
 }
 
-func Up20200310181627(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200310181627(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table transcoding
 (
 	id varchar(255) not null primary key,
@@ -45,8 +45,8 @@ create table player
 	return err
 }
 
-func Down20200310181627(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Down20200310181627(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 drop table transcoding;
 drop table player;
 `)

db/migrations/20200319211049_merge_search_into_main_tables.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20200319211049, Down20200319211049)
 }
 
-func Up20200319211049(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200319211049(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file
 	add full_text varchar(255) default '';
 create index if not exists media_file_full_text
@@ -33,10 +33,10 @@ drop table if exists search;
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan will be performed!")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan will be performed!")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200319211049(_ context.Context, tx *sql.Tx) error {
+func Down20200319211049(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200325185135_add_album_artist_id.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20200325185135, Down20200325185135)
 }
 
-func Up20200325185135(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200325185135(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table album
 	add album_artist_id varchar(255) default '';
 create index album_artist_album_id
@@ -26,10 +26,10 @@ create index media_file_artist_album_id
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan will be performed!")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan will be performed!")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200325185135(_ context.Context, tx *sql.Tx) error {
+func Down20200325185135(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200326090707_fix_album_artists_importing.go

@@ -11,11 +11,11 @@ func init() {
 	goose.AddMigrationContext(Up20200326090707, Down20200326090707)
 }
 
-func Up20200326090707(_ context.Context, tx *sql.Tx) error {
-	notice(tx, "A full rescan will be performed!")
-	return forceFullRescan(tx)
+func Up20200326090707(ctx context.Context, tx *sql.Tx) error {
+	notice(ctx, tx, "A full rescan will be performed!")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200326090707(_ context.Context, tx *sql.Tx) error {
+func Down20200326090707(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200327193744_add_year_range_to_album.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20200327193744, Down20200327193744)
 }
 
-func Up20200327193744(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200327193744(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table album_dg_tmp
 (
 	id varchar(255) not null
@@ -72,10 +72,10 @@ create index album_max_year
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan will be performed!")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan will be performed!")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200327193744(_ context.Context, tx *sql.Tx) error {
+func Down20200327193744(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200404214704_add_indexes.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20200404214704, Down20200404214704)
 }
 
-func Up20200404214704(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200404214704(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create index if not exists media_file_year
 	on media_file (year);
 
@@ -25,6 +25,6 @@ create index if not exists media_file_track_number
 	return err
 }
 
-func Down20200404214704(_ context.Context, tx *sql.Tx) error {
+func Down20200404214704(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200409002249_enable_search_by_tracks_artists.go

@@ -11,11 +11,11 @@ func init() {
 	goose.AddMigrationContext(Up20200409002249, Down20200409002249)
 }
 
-func Up20200409002249(_ context.Context, tx *sql.Tx) error {
-	notice(tx, "A full rescan will be performed to enable search by individual Artist in an Album!")
-	return forceFullRescan(tx)
+func Up20200409002249(ctx context.Context, tx *sql.Tx) error {
+	notice(ctx, tx, "A full rescan will be performed to enable search by individual Artist in an Album!")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200409002249(_ context.Context, tx *sql.Tx) error {
+func Down20200409002249(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200411164603_add_created_and_updated_fields_to_playlists.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20200411164603, Down20200411164603)
 }
 
-func Up20200411164603(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200411164603(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table playlist
 	add created_at datetime;
 alter table playlist
@@ -23,6 +23,6 @@ update playlist
 	return err
 }
 
-func Down20200411164603(_ context.Context, tx *sql.Tx) error {
+func Down20200411164603(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200418110522_reindex_to_fix_album_years.go

@@ -11,11 +11,11 @@ func init() {
 	goose.AddMigrationContext(Up20200418110522, Down20200418110522)
 }
 
-func Up20200418110522(_ context.Context, tx *sql.Tx) error {
-	notice(tx, "A full rescan will be performed to fix search Albums by year")
-	return forceFullRescan(tx)
+func Up20200418110522(ctx context.Context, tx *sql.Tx) error {
+	notice(ctx, tx, "A full rescan will be performed to fix search Albums by year")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200418110522(_ context.Context, tx *sql.Tx) error {
+func Down20200418110522(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200419222708_reindex_to_change_full_text_search.go

@@ -11,11 +11,11 @@ func init() {
 	goose.AddMigrationContext(Up20200419222708, Down20200419222708)
 }
 
-func Up20200419222708(_ context.Context, tx *sql.Tx) error {
-	notice(tx, "A full rescan will be performed to change the search behaviour")
-	return forceFullRescan(tx)
+func Up20200419222708(ctx context.Context, tx *sql.Tx) error {
+	notice(ctx, tx, "A full rescan will be performed to change the search behaviour")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200419222708(_ context.Context, tx *sql.Tx) error {
+func Down20200419222708(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200423204116_add_sort_fields.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20200423204116, Down20200423204116)
 }
 
-func Up20200423204116(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200423204116(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table artist
 	add order_artist_name varchar(255) collate nocase;
 alter table artist
@@ -57,10 +57,10 @@ create index if not exists media_file_order_artist_name
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan will be performed to change the search behaviour")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan will be performed to change the search behaviour")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200423204116(_ context.Context, tx *sql.Tx) error {
+func Down20200423204116(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200508093059_add_artist_song_count.go

@@ -11,18 +11,18 @@ func init() {
 	goose.AddMigrationContext(Up20200508093059, Down20200508093059)
 }
 
-func Up20200508093059(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200508093059(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table artist
 	add song_count integer default 0 not null;
 `)
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan will be performed to calculate artists' song counts")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan will be performed to calculate artists' song counts")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200508093059(_ context.Context, tx *sql.Tx) error {
+func Down20200508093059(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200512104202_add_disc_subtitle.go

@@ -11,18 +11,18 @@ func init() {
 	goose.AddMigrationContext(Up20200512104202, Down20200512104202)
 }
 
-func Up20200512104202(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200512104202(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file 
     add disc_subtitle varchar(255);
     `)
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan will be performed to import disc subtitles")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan will be performed to import disc subtitles")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20200512104202(_ context.Context, tx *sql.Tx) error {
+func Down20200512104202(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200516140647_add_playlist_tracks_table.go

@@ -13,8 +13,8 @@ func init() {
 	goose.AddMigrationContext(Up20200516140647, Down20200516140647)
 }
 
-func Up20200516140647(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20200516140647(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table if not exists playlist_tracks
 (
 	id integer default 0 not null, 
@@ -28,7 +28,7 @@ create unique index if not exists playlist_tracks_pos
 	if err != nil {
 		return err
 	}
-	rows, err := tx.Query("select id, tracks from playlist")
+	rows, err := tx.QueryContext(ctx, "select id, tracks from playlist")
 	if err != nil {
 		return err
 	}
@@ -49,7 +49,7 @@ create unique index if not exists playlist_tracks_pos
 		return err
 	}
 
-	_, err = tx.Exec(`
+	_, err = tx.ExecContext(ctx, `
 create table playlist_dg_tmp
 (
 	id varchar(255) not null
@@ -96,6 +96,6 @@ func Up20200516140647UpdatePlaylistTracks(tx *sql.Tx, id string, tracks string)
 	return nil
 }
 
-func Down20200516140647(_ context.Context, tx *sql.Tx) error {
+func Down20200516140647(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200608153717_referential_integrity.go

@@ -11,46 +11,46 @@ func init() {
 	goose.AddMigrationContext(Up20200608153717, Down20200608153717)
 }
 
-func Up20200608153717(_ context.Context, tx *sql.Tx) error {
+func Up20200608153717(ctx context.Context, tx *sql.Tx) error {
 	// First delete dangling players
-	_, err := tx.Exec(`
+	_, err := tx.ExecContext(ctx, `
 delete from player where user_name not in (select user_name from user)`)
 	if err != nil {
 		return err
 	}
 
 	// Also delete dangling players
-	_, err = tx.Exec(`
+	_, err = tx.ExecContext(ctx, `
 delete from playlist where owner not in (select user_name from user)`)
 	if err != nil {
 		return err
 	}
 
 	// Also delete dangling playlist tracks
-	_, err = tx.Exec(`
+	_, err = tx.ExecContext(ctx, `
 delete from playlist_tracks where playlist_id not in (select id from playlist)`)
 	if err != nil {
 		return err
 	}
 
 	// Add foreign key to player table
-	err = updatePlayer_20200608153717(tx)
+	err = updatePlayer_20200608153717(ctx, tx)
 	if err != nil {
 		return err
 	}
 
 	// Add foreign key to playlist table
-	err = updatePlaylist_20200608153717(tx)
+	err = updatePlaylist_20200608153717(ctx, tx)
 	if err != nil {
 		return err
 	}
 
 	// Add foreign keys to playlist_tracks table
-	return updatePlaylistTracks_20200608153717(tx)
+	return updatePlaylistTracks_20200608153717(ctx, tx)
 }
 
-func updatePlayer_20200608153717(tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func updatePlayer_20200608153717(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table player_dg_tmp
 (
 	id varchar(255) not null
@@ -77,8 +77,8 @@ alter table player_dg_tmp rename to player;
 	return err
 }
 
-func updatePlaylist_20200608153717(tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func updatePlaylist_20200608153717(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table playlist_dg_tmp
 (
 	id varchar(255) not null
@@ -108,8 +108,8 @@ create index playlist_name
 	return err
 }
 
-func updatePlaylistTracks_20200608153717(tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func updatePlaylistTracks_20200608153717(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table playlist_tracks_dg_tmp
 (
 	id integer default 0 not null,
@@ -133,6 +133,6 @@ create unique index playlist_tracks_pos
 	return err
 }
 
-func Down20200608153717(_ context.Context, tx *sql.Tx) error {
+func Down20200608153717(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200706231659_add_default_transcodings.go

@@ -13,8 +13,8 @@ func init() {
 	goose.AddMigrationContext(upAddDefaultTranscodings, downAddDefaultTranscodings)
 }
 
-func upAddDefaultTranscodings(_ context.Context, tx *sql.Tx) error {
-	row := tx.QueryRow("SELECT COUNT(*) FROM transcoding")
+func upAddDefaultTranscodings(ctx context.Context, tx *sql.Tx) error {
+	row := tx.QueryRowContext(ctx, "SELECT COUNT(*) FROM transcoding")
 	var count int
 	err := row.Scan(&count)
 	if err != nil {
@@ -38,6 +38,6 @@ func upAddDefaultTranscodings(_ context.Context, tx *sql.Tx) error {
 	return nil
 }
 
-func downAddDefaultTranscodings(_ context.Context, tx *sql.Tx) error {
+func downAddDefaultTranscodings(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200710211442_add_playlist_path.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddPlaylistPath, downAddPlaylistPath)
 }
 
-func upAddPlaylistPath(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddPlaylistPath(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table playlist
 	add path string default '' not null;
 
@@ -23,6 +23,6 @@ alter table playlist
 	return err
 }
 
-func downAddPlaylistPath(_ context.Context, tx *sql.Tx) error {
+func downAddPlaylistPath(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200731095603_create_play_queues_table.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upCreatePlayQueuesTable, downCreatePlayQueuesTable)
 }
 
-func upCreatePlayQueuesTable(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upCreatePlayQueuesTable(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table playqueue
 (
     id         varchar(255) not null primary key,
@@ -32,6 +32,6 @@ create table playqueue
 	return err
 }
 
-func downCreatePlayQueuesTable(_ context.Context, tx *sql.Tx) error {
+func downCreatePlayQueuesTable(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200801101355_create_bookmark_table.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upCreateBookmarkTable, downCreateBookmarkTable)
 }
 
-func upCreateBookmarkTable(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upCreateBookmarkTable(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table bookmark
 (
     user_id    varchar(255) not null
@@ -49,6 +49,6 @@ alter table playqueue_dg_tmp rename to playqueue;
 	return err
 }
 
-func downCreateBookmarkTable(_ context.Context, tx *sql.Tx) error {
+func downCreateBookmarkTable(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20200819111809_drop_email_unique_constraint.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upDropEmailUniqueConstraint, downDropEmailUniqueConstraint)
 }
 
-func upDropEmailUniqueConstraint(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upDropEmailUniqueConstraint(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table user_dg_tmp
 (
 	id varchar(255) not null
@@ -38,6 +38,6 @@ alter table user_dg_tmp rename to user;
 	return err
 }
 
-func downDropEmailUniqueConstraint(_ context.Context, tx *sql.Tx) error {
+func downDropEmailUniqueConstraint(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20201003111749_add_starred_at_index.go

@@ -11,14 +11,14 @@ func init() {
 	goose.AddMigrationContext(Up20201003111749, Down20201003111749)
 }
 
-func Up20201003111749(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20201003111749(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create index if not exists annotation_starred_at
 	on annotation (starred_at);
     `)
 	return err
 }
 
-func Down20201003111749(_ context.Context, tx *sql.Tx) error {
+func Down20201003111749(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20201010162350_add_album_size.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20201010162350, Down20201010162350)
 }
 
-func Up20201010162350(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20201010162350(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table album
 	add size integer default 0 not null;
 create index if not exists album_size
@@ -28,7 +28,7 @@ where id not null;`)
 	return err
 }
 
-func Down20201010162350(_ context.Context, tx *sql.Tx) error {
+func Down20201010162350(ctx context.Context, tx *sql.Tx) error {
 	// This code is executed when the migration is rolled back.
 	return nil
 }

db/migrations/20201012210022_add_artist_playlist_size.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20201012210022, Down20201012210022)
 }
 
-func Up20201012210022(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20201012210022(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table artist
 	add size integer default 0 not null;
 create index if not exists artist_size
@@ -40,6 +40,6 @@ update playlist set size = ifnull((
 	return err
 }
 
-func Down20201012210022(_ context.Context, tx *sql.Tx) error {
+func Down20201012210022(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20201021085410_add_mbids.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20201021085410, Down20201021085410)
 }
 
-func Up20201021085410(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20201021085410(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file
 	add mbz_track_id varchar(255);
 alter table media_file
@@ -49,11 +49,11 @@ alter table artist
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan needs to be performed to import more tags")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan needs to be performed to import more tags")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20201021085410(_ context.Context, tx *sql.Tx) error {
+func Down20201021085410(ctx context.Context, tx *sql.Tx) error {
 	// This code is executed when the migration is rolled back.
 	return nil
 }

db/migrations/20201021093209_add_media_file_indexes.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20201021093209, Down20201021093209)
 }
 
-func Up20201021093209(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20201021093209(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create index if not exists media_file_artist
 	on media_file (artist);
 create index if not exists media_file_album_artist
@@ -23,6 +23,6 @@ create index if not exists media_file_mbz_track_id
 	return err
 }
 
-func Down20201021093209(_ context.Context, tx *sql.Tx) error {
+func Down20201021093209(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20201021135455_add_media_file_artist_index.go

@@ -11,14 +11,14 @@ func init() {
 	goose.AddMigrationContext(Up20201021135455, Down20201021135455)
 }
 
-func Up20201021135455(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20201021135455(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create index if not exists media_file_artist_id
 	on media_file (artist_id);
 `)
 	return err
 }
 
-func Down20201021135455(_ context.Context, tx *sql.Tx) error {
+func Down20201021135455(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20201030162009_add_artist_info_table.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddArtistImageUrl, downAddArtistImageUrl)
 }
 
-func upAddArtistImageUrl(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddArtistImageUrl(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table artist
 	add biography varchar(255) default '' not null;
 alter table artist
@@ -31,6 +31,6 @@ alter table artist
 	return err
 }
 
-func downAddArtistImageUrl(_ context.Context, tx *sql.Tx) error {
+func downAddArtistImageUrl(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20201110205344_add_comments_and_lyrics.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(Up20201110205344, Down20201110205344)
 }
 
-func Up20201110205344(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20201110205344(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file
 	add comment varchar;
 alter table media_file
@@ -24,10 +24,10 @@ alter table album
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan will be performed to import comments and lyrics")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan will be performed to import comments and lyrics")
+	return forceFullRescan(ctx, tx)
 }
 
-func Down20201110205344(_ context.Context, tx *sql.Tx) error {
+func Down20201110205344(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20201128100726_add_real-path_option.go

@@ -11,14 +11,14 @@ func init() {
 	goose.AddMigrationContext(Up20201128100726, Down20201128100726)
 }
 
-func Up20201128100726(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20201128100726(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table player
 	add report_real_path bool default FALSE not null;
 `)
 	return err
 }
 
-func Down20201128100726(_ context.Context, tx *sql.Tx) error {
+func Down20201128100726(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20201213124814_add_all_artist_ids_to_album.go

@@ -13,8 +13,8 @@ func init() {
 	goose.AddMigrationContext(Up20201213124814, Down20201213124814)
 }
 
-func Up20201213124814(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func Up20201213124814(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table album
 	add all_artist_ids varchar;
 
@@ -25,11 +25,11 @@ create index if not exists album_all_artist_ids
 		return err
 	}
 
-	return updateAlbums20201213124814(tx)
+	return updateAlbums20201213124814(ctx, tx)
 }
 
-func updateAlbums20201213124814(tx *sql.Tx) error {
-	rows, err := tx.Query(`
+func updateAlbums20201213124814(ctx context.Context, tx *sql.Tx) error {
+	rows, err := tx.QueryContext(ctx, `
 select a.id, a.name, a.artist_id, a.album_artist_id, group_concat(mf.artist_id, ' ') 
        from album a left join media_file mf on a.id = mf.album_id group by a.id
    `)
@@ -59,6 +59,6 @@ select a.id, a.name, a.artist_id, a.album_artist_id, group_concat(mf.artist_id,
 	return rows.Err()
 }
 
-func Down20201213124814(_ context.Context, tx *sql.Tx) error {
+func Down20201213124814(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210322132848_add_timestamp_indexes.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddTimestampIndexesGo, downAddTimestampIndexesGo)
 }
 
-func upAddTimestampIndexesGo(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddTimestampIndexesGo(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create index if not exists album_updated_at
 	on album (updated_at);
 create index if not exists album_created_at
@@ -29,6 +29,6 @@ create index if not exists media_file_updated_at
 	return err
 }
 
-func downAddTimestampIndexesGo(_ context.Context, tx *sql.Tx) error {
+func downAddTimestampIndexesGo(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210418232815_fix_album_comments.go

@@ -14,10 +14,10 @@ func init() {
 	goose.AddMigrationContext(upFixAlbumComments, downFixAlbumComments)
 }
 
-func upFixAlbumComments(_ context.Context, tx *sql.Tx) error {
+func upFixAlbumComments(ctx context.Context, tx *sql.Tx) error {
 	//nolint:gosec
-	rows, err := tx.Query(`
-	SELECT album.id, group_concat(media_file.comment, '` + consts.Zwsp + `') FROM album, media_file WHERE media_file.album_id = album.id GROUP BY album.id;
+	rows, err := tx.QueryContext(ctx, `
+	SELECT album.id, group_concat(media_file.comment, '`+consts.Zwsp+`') FROM album, media_file WHERE media_file.album_id = album.id GROUP BY album.id;
 	   `)
 	if err != nil {
 		return err
@@ -49,7 +49,7 @@ func upFixAlbumComments(_ context.Context, tx *sql.Tx) error {
 	return rows.Err()
 }
 
-func downFixAlbumComments(_ context.Context, tx *sql.Tx) error {
+func downFixAlbumComments(_ context.Context, _ *sql.Tx) error {
 	return nil
 }
 

db/migrations/20210430212322_add_bpm_metadata.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddBpmMetadata, downAddBpmMetadata)
 }
 
-func upAddBpmMetadata(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddBpmMetadata(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file
     add bpm integer;
 
@@ -22,10 +22,10 @@ create index if not exists media_file_bpm
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan needs to be performed to import more tags")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan needs to be performed to import more tags")
+	return forceFullRescan(ctx, tx)
 }
 
-func downAddBpmMetadata(_ context.Context, tx *sql.Tx) error {
+func downAddBpmMetadata(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210530121921_create_shares_table.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upCreateSharesTable, downCreateSharesTable)
 }
 
-func upCreateSharesTable(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upCreateSharesTable(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table share
 (
 	id             varchar(255) not null primary key,
@@ -30,6 +30,6 @@ create table share
 	return err
 }
 
-func downCreateSharesTable(_ context.Context, tx *sql.Tx) error {
+func downCreateSharesTable(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210601231734_update_share_fieldnames.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upUpdateShareFieldNames, downUpdateShareFieldNames)
 }
 
-func upUpdateShareFieldNames(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upUpdateShareFieldNames(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table share rename column expires to expires_at;
 alter table share rename column created to created_at;
 alter table share rename column last_visited to last_visited_at;
@@ -21,6 +21,6 @@ alter table share rename column last_visited to last_visited_at;
 	return err
 }
 
-func downUpdateShareFieldNames(_ context.Context, tx *sql.Tx) error {
+func downUpdateShareFieldNames(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210616150710_encrypt_all_passwords.go

@@ -16,7 +16,7 @@ func init() {
 }
 
 func upEncodeAllPasswords(ctx context.Context, tx *sql.Tx) error {
-	rows, err := tx.Query(`SELECT id, user_name, password from user;`)
+	rows, err := tx.QueryContext(ctx, `SELECT id, user_name, password from user;`)
 	if err != nil {
 		return err
 	}
@@ -51,6 +51,6 @@ func upEncodeAllPasswords(ctx context.Context, tx *sql.Tx) error {
 	return rows.Err()
 }
 
-func downEncodeAllPasswords(_ context.Context, tx *sql.Tx) error {
+func downEncodeAllPasswords(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210619231716_drop_player_name_unique_constraint.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upDropPlayerNameUniqueConstraint, downDropPlayerNameUniqueConstraint)
 }
 
-func upDropPlayerNameUniqueConstraint(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upDropPlayerNameUniqueConstraint(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table player_dg_tmp
 (
 	id varchar(255) not null
@@ -43,6 +43,6 @@ create index if not exists player_name
 	return err
 }
 
-func downDropPlayerNameUniqueConstraint(_ context.Context, tx *sql.Tx) error {
+func downDropPlayerNameUniqueConstraint(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210623155401_add_user_prefs_player_scrobbler_enabled.go

@@ -11,16 +11,16 @@ func init() {
 	goose.AddMigrationContext(upAddUserPrefsPlayerScrobblerEnabled, downAddUserPrefsPlayerScrobblerEnabled)
 }
 
-func upAddUserPrefsPlayerScrobblerEnabled(_ context.Context, tx *sql.Tx) error {
-	err := upAddUserPrefs(tx)
+func upAddUserPrefsPlayerScrobblerEnabled(ctx context.Context, tx *sql.Tx) error {
+	err := upAddUserPrefs(ctx, tx)
 	if err != nil {
 		return err
 	}
-	return upPlayerScrobblerEnabled(tx)
+	return upPlayerScrobblerEnabled(ctx, tx)
 }
 
-func upAddUserPrefs(tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddUserPrefs(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table user_props
 (
     user_id varchar not null,
@@ -33,13 +33,13 @@ create table user_props
 	return err
 }
 
-func upPlayerScrobblerEnabled(tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upPlayerScrobblerEnabled(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table player add scrobble_enabled bool default true;
 `)
 	return err
 }
 
-func downAddUserPrefsPlayerScrobblerEnabled(_ context.Context, tx *sql.Tx) error {
+func downAddUserPrefsPlayerScrobblerEnabled(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210625223901_add_referential_integrity_to_user_props.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddReferentialIntegrityToUserProps, downAddReferentialIntegrityToUserProps)
 }
 
-func upAddReferentialIntegrityToUserProps(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddReferentialIntegrityToUserProps(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table user_props_dg_tmp
 (
 	user_id varchar not null
@@ -34,6 +34,6 @@ alter table user_props_dg_tmp rename to user_props;
 	return err
 }
 
-func downAddReferentialIntegrityToUserProps(_ context.Context, tx *sql.Tx) error {
+func downAddReferentialIntegrityToUserProps(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210626213026_add_scrobble_buffer.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddScrobbleBuffer, downAddScrobbleBuffer)
 }
 
-func upAddScrobbleBuffer(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddScrobbleBuffer(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table if not exists scrobble_buffer
 (
 	user_id varchar not null
@@ -34,6 +34,6 @@ create table if not exists scrobble_buffer
 	return err
 }
 
-func downAddScrobbleBuffer(_ context.Context, tx *sql.Tx) error {
+func downAddScrobbleBuffer(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210715151153_add_genre_tables.go

@@ -11,9 +11,9 @@ func init() {
 	goose.AddMigrationContext(upAddGenreTables, downAddGenreTables)
 }
 
-func upAddGenreTables(_ context.Context, tx *sql.Tx) error {
-	notice(tx, "A full rescan will be performed to import multiple genres!")
-	_, err := tx.Exec(`
+func upAddGenreTables(ctx context.Context, tx *sql.Tx) error {
+	notice(ctx, tx, "A full rescan will be performed to import multiple genres!")
+	_, err := tx.ExecContext(ctx, `
 create table if not exists genre
 (
   id varchar not null primary key,
@@ -61,9 +61,9 @@ create table if not exists  artist_genres
 	if err != nil {
 		return err
 	}
-	return forceFullRescan(tx)
+	return forceFullRescan(ctx, tx)
 }
 
-func downAddGenreTables(_ context.Context, tx *sql.Tx) error {
+func downAddGenreTables(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20210821212604_add_mediafile_channels.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddMediafileChannels, downAddMediafileChannels)
 }
 
-func upAddMediafileChannels(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddMediafileChannels(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file
     add channels integer;
 
@@ -22,10 +22,10 @@ create index if not exists media_file_channels
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan needs to be performed to import more tags")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan needs to be performed to import more tags")
+	return forceFullRescan(ctx, tx)
 }
 
-func downAddMediafileChannels(_ context.Context, tx *sql.Tx) error {
+func downAddMediafileChannels(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20211008205505_add_smart_playlist.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddSmartPlaylist, downAddSmartPlaylist)
 }
 
-func upAddSmartPlaylist(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddSmartPlaylist(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table playlist
 	add column rules varchar null;
 alter table playlist
@@ -33,6 +33,6 @@ create unique index playlist_fields_idx
 	return err
 }
 
-func downAddSmartPlaylist(_ context.Context, tx *sql.Tx) error {
+func downAddSmartPlaylist(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20211023184825_add_order_title_to_media_file.go

@@ -14,8 +14,8 @@ func init() {
 	goose.AddMigrationContext(upAddOrderTitleToMediaFile, downAddOrderTitleToMediaFile)
 }
 
-func upAddOrderTitleToMediaFile(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddOrderTitleToMediaFile(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table main.media_file
 	add order_title varchar null collate NOCASE;
 create index if not exists media_file_order_title
@@ -25,12 +25,12 @@ create index if not exists media_file_order_title
 		return err
 	}
 
-	return upAddOrderTitleToMediaFile_populateOrderTitle(tx)
+	return upAddOrderTitleToMediaFile_populateOrderTitle(ctx, tx)
 }
 
 //goland:noinspection GoSnakeCaseUsage
-func upAddOrderTitleToMediaFile_populateOrderTitle(tx *sql.Tx) error {
-	rows, err := tx.Query(`select id, title from media_file`)
+func upAddOrderTitleToMediaFile_populateOrderTitle(ctx context.Context, tx *sql.Tx) error {
+	rows, err := tx.QueryContext(ctx, `select id, title from media_file`)
 	if err != nil {
 		return err
 	}
@@ -57,6 +57,6 @@ func upAddOrderTitleToMediaFile_populateOrderTitle(tx *sql.Tx) error {
 	return rows.Err()
 }
 
-func downAddOrderTitleToMediaFile(_ context.Context, tx *sql.Tx) error {
+func downAddOrderTitleToMediaFile(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20211026191915_unescape_lyrics_and_comments.go

@@ -13,8 +13,8 @@ func init() {
 	goose.AddMigrationContext(upUnescapeLyricsAndComments, downUnescapeLyricsAndComments)
 }
 
-func upUnescapeLyricsAndComments(_ context.Context, tx *sql.Tx) error {
-	rows, err := tx.Query(`select id, comment, lyrics, title from media_file`)
+func upUnescapeLyricsAndComments(ctx context.Context, tx *sql.Tx) error {
+	rows, err := tx.QueryContext(ctx, `select id, comment, lyrics, title from media_file`)
 	if err != nil {
 		return err
 	}
@@ -43,6 +43,6 @@ func upUnescapeLyricsAndComments(_ context.Context, tx *sql.Tx) error {
 	return rows.Err()
 }
 
-func downUnescapeLyricsAndComments(_ context.Context, tx *sql.Tx) error {
+func downUnescapeLyricsAndComments(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20211029213200_add_userid_to_playlist.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddUseridToPlaylist, downAddUseridToPlaylist)
 }
 
-func upAddUseridToPlaylist(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddUseridToPlaylist(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table playlist_dg_tmp
 (
 	id varchar(255) not null
@@ -56,6 +56,6 @@ create index playlist_updated_at
 	return err
 }
 
-func downAddUseridToPlaylist(_ context.Context, tx *sql.Tx) error {
+func downAddUseridToPlaylist(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20211102215414_add_alphabetical_by_artist_index.go

@@ -11,14 +11,14 @@ func init() {
 	goose.AddMigrationContext(upAddAlphabeticalByArtistIndex, downAddAlphabeticalByArtistIndex)
 }
 
-func upAddAlphabeticalByArtistIndex(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddAlphabeticalByArtistIndex(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create index album_alphabetical_by_artist 
     ON album(compilation, order_album_artist_name, order_album_name)
 `)
 	return err
 }
 
-func downAddAlphabeticalByArtistIndex(_ context.Context, tx *sql.Tx) error {
+func downAddAlphabeticalByArtistIndex(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20211105162746_remove_invalid_artist_ids.go

@@ -11,13 +11,13 @@ func init() {
 	goose.AddMigrationContext(upRemoveInvalidArtistIds, downRemoveInvalidArtistIds)
 }
 
-func upRemoveInvalidArtistIds(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upRemoveInvalidArtistIds(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 update media_file set artist_id = '' where not exists(select 1 from artist where id = artist_id)
 `)
 	return err
 }
 
-func downRemoveInvalidArtistIds(_ context.Context, tx *sql.Tx) error {
+func downRemoveInvalidArtistIds(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20220724231849_add_musicbrainz_release_track_id.go

@@ -11,19 +11,19 @@ func init() {
 	goose.AddMigrationContext(upAddMusicbrainzReleaseTrackId, downAddMusicbrainzReleaseTrackId)
 }
 
-func upAddMusicbrainzReleaseTrackId(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddMusicbrainzReleaseTrackId(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file
 	add mbz_release_track_id varchar(255);
 `)
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan needs to be performed to import more tags")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan needs to be performed to import more tags")
+	return forceFullRescan(ctx, tx)
 }
 
-func downAddMusicbrainzReleaseTrackId(_ context.Context, tx *sql.Tx) error {
+func downAddMusicbrainzReleaseTrackId(ctx context.Context, tx *sql.Tx) error {
 	// This code is executed when the migration is rolled back.
 	return nil
 }

db/migrations/20221219112733_add_album_image_paths.go

@@ -11,17 +11,17 @@ func init() {
 	goose.AddMigrationContext(upAddAlbumImagePaths, downAddAlbumImagePaths)
 }
 
-func upAddAlbumImagePaths(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddAlbumImagePaths(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table main.album add image_files varchar;
 `)
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan needs to be performed to import all album images")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan needs to be performed to import all album images")
+	return forceFullRescan(ctx, tx)
 }
 
-func downAddAlbumImagePaths(_ context.Context, tx *sql.Tx) error {
+func downAddAlbumImagePaths(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20221219140528_remove_cover_art_id.go

@@ -11,18 +11,18 @@ func init() {
 	goose.AddMigrationContext(upRemoveCoverArtId, downRemoveCoverArtId)
 }
 
-func upRemoveCoverArtId(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upRemoveCoverArtId(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table album drop column cover_art_id;
 alter table album rename column cover_art_path to embed_art_path
 `)
 	if err != nil {
 		return err
 	}
-	notice(tx, "A full rescan needs to be performed to import all album images")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan needs to be performed to import all album images")
+	return forceFullRescan(ctx, tx)
 }
 
-func downRemoveCoverArtId(_ context.Context, tx *sql.Tx) error {
+func downRemoveCoverArtId(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230112111457_add_album_paths.go

@@ -16,15 +16,15 @@ func init() {
 	goose.AddMigrationContext(upAddAlbumPaths, downAddAlbumPaths)
 }
 
-func upAddAlbumPaths(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`alter table album add paths varchar;`)
+func upAddAlbumPaths(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `alter table album add paths varchar;`)
 	if err != nil {
 		return err
 	}
 
 	//nolint:gosec
-	rows, err := tx.Query(`
-	select album_id, group_concat(path, '` + consts.Zwsp + `') from media_file group by album_id
+	rows, err := tx.QueryContext(ctx, `
+	select album_id, group_concat(path, '`+consts.Zwsp+`') from media_file group by album_id
 	`)
 	if err != nil {
 		return err
@@ -63,6 +63,6 @@ func upAddAlbumPathsDirs(filePaths string) string {
 	return strings.Join(dirs, string(filepath.ListSeparator))
 }
 
-func downAddAlbumPaths(_ context.Context, tx *sql.Tx) error {
+func downAddAlbumPaths(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230114121537_touch_playlists.go

@@ -11,11 +11,11 @@ func init() {
 	goose.AddMigrationContext(upTouchPlaylists, downTouchPlaylists)
 }
 
-func upTouchPlaylists(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`update playlist set updated_at = datetime('now');`)
+func upTouchPlaylists(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `update playlist set updated_at = datetime('now');`)
 	return err
 }
 
-func downTouchPlaylists(_ context.Context, tx *sql.Tx) error {
+func downTouchPlaylists(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230115103212_create_internet_radio.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upCreateInternetRadio, downCreateInternetRadio)
 }
 
-func upCreateInternetRadio(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upCreateInternetRadio(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 create table if not exists radio
 (
     id            varchar(255) not null primary key,
@@ -26,6 +26,6 @@ create table if not exists radio
 	return err
 }
 
-func downCreateInternetRadio(_ context.Context, tx *sql.Tx) error {
+func downCreateInternetRadio(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230117155559_add_replaygain_metadata.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddReplaygainMetadata, downAddReplaygainMetadata)
 }
 
-func upAddReplaygainMetadata(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddReplaygainMetadata(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file add 
 	rg_album_gain real;
 alter table media_file add 
@@ -26,10 +26,10 @@ alter table media_file add
 		return err
 	}
 
-	notice(tx, "A full rescan needs to be performed to import more tags")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan needs to be performed to import more tags")
+	return forceFullRescan(ctx, tx)
 }
 
-func downAddReplaygainMetadata(_ context.Context, tx *sql.Tx) error {
+func downAddReplaygainMetadata(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230117180400_add_album_info.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddAlbumInfo, downAddAlbumInfo)
 }
 
-func upAddAlbumInfo(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddAlbumInfo(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table album
 	add description varchar(255) default '' not null;
 alter table album
@@ -29,6 +29,6 @@ alter table album
 	return err
 }
 
-func downAddAlbumInfo(_ context.Context, tx *sql.Tx) error {
+func downAddAlbumInfo(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230119152657_recreate_share_table.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddMissingShareInfo, downAddMissingShareInfo)
 }
 
-func upAddMissingShareInfo(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddMissingShareInfo(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 drop table if exists share;
 create table share
 (
@@ -37,6 +37,6 @@ create table share
 	return err
 }
 
-func downAddMissingShareInfo(_ context.Context, tx *sql.Tx) error {
+func downAddMissingShareInfo(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230202143713_change_path_list_separator.go

@@ -16,10 +16,10 @@ func init() {
 	goose.AddMigrationContext(upChangePathListSeparator, downChangePathListSeparator)
 }
 
-func upChangePathListSeparator(_ context.Context, tx *sql.Tx) error {
+func upChangePathListSeparator(ctx context.Context, tx *sql.Tx) error {
 	//nolint:gosec
-	rows, err := tx.Query(`
-	select album_id, group_concat(path, '` + consts.Zwsp + `') from media_file group by album_id
+	rows, err := tx.QueryContext(ctx, `
+	select album_id, group_concat(path, '`+consts.Zwsp+`') from media_file group by album_id
 	`)
 	if err != nil {
 		return err
@@ -58,6 +58,6 @@ func upChangePathListSeparatorDirs(filePaths string) string {
 	return strings.Join(dirs, consts.Zwsp)
 }
 
-func downChangePathListSeparator(_ context.Context, tx *sql.Tx) error {
+func downChangePathListSeparator(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230209181414_change_image_files_list_separator.go

@@ -16,8 +16,8 @@ func init() {
 	goose.AddMigrationContext(upChangeImageFilesListSeparator, downChangeImageFilesListSeparator)
 }
 
-func upChangeImageFilesListSeparator(_ context.Context, tx *sql.Tx) error {
-	rows, err := tx.Query(`select id, image_files from album`)
+func upChangeImageFilesListSeparator(ctx context.Context, tx *sql.Tx) error {
+	rows, err := tx.QueryContext(ctx, `select id, image_files from album`)
 	if err != nil {
 		return err
 	}
@@ -54,7 +54,7 @@ func upChangeImageFilesListSeparatorDirs(filePaths string) string {
 	return strings.Join(allPaths, consts.Zwsp)
 }
 
-func downChangeImageFilesListSeparator(_ context.Context, tx *sql.Tx) error {
+func downChangeImageFilesListSeparator(ctx context.Context, tx *sql.Tx) error {
 	// This code is executed when the migration is rolled back.
 	return nil
 }

db/migrations/20230310222612_add_download_to_share.go

@@ -11,14 +11,14 @@ func init() {
 	goose.AddMigrationContext(upAddDownloadToShare, downAddDownloadToShare)
 }
 
-func upAddDownloadToShare(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddDownloadToShare(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table share
 	add downloadable bool not null default false;
 `)
 	return err
 }
 
-func downAddDownloadToShare(_ context.Context, tx *sql.Tx) error {
+func downAddDownloadToShare(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230515184510_add_release_date.go

@@ -11,8 +11,8 @@ func init() {
 	goose.AddMigrationContext(upAddRelRecYear, downAddRelRecYear)
 }
 
-func upAddRelRecYear(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upAddRelRecYear(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file
     add date varchar(255) default '' not null;
 alter table media_file
@@ -41,10 +41,10 @@ alter table album
 		return err
 	}
 
-	notice(tx, "A full rescan needs to be performed to import more tags")
-	return forceFullRescan(tx)
+	notice(ctx, tx, "A full rescan needs to be performed to import more tags")
+	return forceFullRescan(ctx, tx)
 }
 
-func downAddRelRecYear(_ context.Context, tx *sql.Tx) error {
+func downAddRelRecYear(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20230616214944_rename_musicbrainz_recording_id.go

@@ -11,16 +11,16 @@ func init() {
 	goose.AddMigrationContext(upRenameMusicbrainzRecordingId, downRenameMusicbrainzRecordingId)
 }
 
-func upRenameMusicbrainzRecordingId(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func upRenameMusicbrainzRecordingId(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file
 	rename column mbz_track_id to mbz_recording_id;
 `)
 	return err
 }
 
-func downRenameMusicbrainzRecordingId(_ context.Context, tx *sql.Tx) error {
-	_, err := tx.Exec(`
+func downRenameMusicbrainzRecordingId(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx, `
 alter table media_file
 	rename column mbz_recording_id to mbz_track_id;
 `)

db/migrations/20231209211223_alter_lyric_column.go

@@ -29,7 +29,7 @@ func upAlterLyricColumn(ctx context.Context, tx *sql.Tx) error {
 		return err
 	}
 
-	rows, err := tx.Query(`select id, lyrics_old FROM media_file WHERE lyrics_old <> '';`)
+	rows, err := tx.QueryContext(ctx, `select id, lyrics_old FROM media_file WHERE lyrics_old <> '';`)
 	if err != nil {
 		return err
 	}
@@ -46,12 +46,12 @@ func upAlterLyricColumn(ctx context.Context, tx *sql.Tx) error {
 			continue
 		}
 
-		lyrics, err := model.ToLyrics("xxx", lyrics.String)
+		parsed, err := model.ParseLyrics(".lrc", "xxx", []byte(lyrics.String))
 		if err != nil {
 			return err
 		}
 
-		text, err := json.Marshal(model.LyricList{*lyrics})
+		text, err := json.Marshal(parsed)
 		if err != nil {
 			return err
 		}
@@ -72,7 +72,7 @@ func upAlterLyricColumn(ctx context.Context, tx *sql.Tx) error {
 		return err
 	}
 
-	notice(tx, "A full rescan should be performed to pick up additional lyrics (existing lyrics have been preserved)")
+	notice(ctx, tx, "A full rescan should be performed to pick up additional lyrics (existing lyrics have been preserved)")
 	return nil
 }
 

db/migrations/20240122223340_add_default_values_to_null_columns.go.go

@@ -558,6 +558,6 @@ create index media_file_mbz_track_id
 	return err
 }
 
-func Down20240122223340(context.Context, *sql.Tx) error {
+func Down20240122223340(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20240511210036_add_sample_rate.go

@@ -19,7 +19,7 @@ alter table media_file
 create index if not exists media_file_sample_rate
 	on media_file (sample_rate);
 `)
-	notice(tx, "A full rescan should be performed to pick up additional tags")
+	notice(ctx, tx, "A full rescan should be performed to pick up additional tags")
 	return err
 }
 

db/migrations/20240629152843_remove_annotation_id.go

@@ -61,6 +61,6 @@ create index annotation_starred_at
 	return err
 }
 
-func downRemoveAnnotationId(ctx context.Context, tx *sql.Tx) error {
+func downRemoveAnnotationId(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20241026183640_support_new_scanner.go

@@ -97,8 +97,8 @@ insert into property (id, value) values ('PIDTrack', 'track_legacy') on conflict
 insert into property (id, value) values ('PIDAlbum', 'album_legacy') on conflict do nothing;
 `),
 		func() error {
-			notice(tx, "A full scan will be triggered to populate the new tables. This may take a while.")
-			return forceFullRescan(tx)
+			notice(ctx, tx, "A full scan will be triggered to populate the new tables. This may take a while.")
+			return forceFullRescan(ctx, tx)
 		},
 	)
 }
@@ -314,6 +314,6 @@ alter table artist
 	}
 }
 
-func downSupportNewScanner(context.Context, *sql.Tx) error {
+func downSupportNewScanner(_ context.Context, _ *sql.Tx) error {
 	return nil
 }

db/migrations/20250611010101_playqueue_current_to_index.go

@@ -75,6 +75,6 @@ create table playqueue_dg_tmp(
 	return err
 }
 
-func downPlayQueueCurrentToIndex(ctx context.Context, tx *sql.Tx) error {
+func downPlayQueueCurrentToIndex(_ context.Context, _ *sql.Tx) error {
 	return nil
 }