Merge a65947692b911a02db2cc621dd3a6fdfdc124ff5 into a00152397e0807ec906768d79f3e619adf43b3c3

Fixed two bugs in album cover art resolution for multi-disc layouts:

1. compareImageFiles now sorts by path depth (shallower first) when basenames
   tie, so album-root images like Artist/Album/cover.jpg are preferred over
   disc-subfolder images like Artist/Album/CD1/cover.jpg.

2. commonParentFolder now includes the parent folder for single-disc-subfolder
   albums, with a Path != "." guard to avoid pulling artist-folder images.

Closes #5376

.devcontainer/Dockerfile

@@ -13,17 +13,5 @@ RUN if [ "${INSTALL_NODE}" = "true" ]; then su vscode -c "source /usr/local/shar
 RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
     && apt-get -y install --no-install-recommends ffmpeg
 
-# Install TagLib from cross-taglib releases
-ARG CROSS_TAGLIB_VERSION="2.2.0-1"
-ARG TARGETARCH
-RUN DOWNLOAD_ARCH="linux-${TARGETARCH}" \
-    && wget -q "https://github.com/navidrome/cross-taglib/releases/download/v${CROSS_TAGLIB_VERSION}/taglib-${DOWNLOAD_ARCH}.tar.gz" -O /tmp/cross-taglib.tar.gz \
-    && tar -xzf /tmp/cross-taglib.tar.gz -C /usr --strip-components=1 \
-    && mv /usr/include/taglib/* /usr/include/ \
-    && rmdir /usr/include/taglib \
-    && rm /tmp/cross-taglib.tar.gz /usr/provenance.json
-
-ENV CGO_CFLAGS_ALLOW="--define-prefix"
-
 # [Optional] Uncomment this line to install global node packages.
 # RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

.devcontainer/devcontainer.json

@@ -4,11 +4,10 @@
 		"dockerfile": "Dockerfile",
 		"args": {
 			// Update the VARIANT arg to pick a version of Go: 1, 1.15, 1.14
-			"VARIANT": "1.25",
+			"VARIANT": "1.26",
 			// Options
 			"INSTALL_NODE": "true",
-			"NODE_VERSION": "v24",
-			"CROSS_TAGLIB_VERSION": "2.2.0-1"
+			"NODE_VERSION": "v24"
 		}
 	},
 	"workspaceMount": "",

.github/actions/download-taglib/action.yml

@@ -1,23 +0,0 @@
-name: 'Download TagLib'
-description: 'Downloads and extracts the TagLib library, adding it to PKG_CONFIG_PATH'
-inputs:
-  version:
-    description: 'Version of TagLib to download'
-    required: true
-  platform:
-    description: 'Platform to download TagLib for'
-    default: 'linux-amd64'
-runs:
-  using: 'composite'
-  steps:
-    - name: Download TagLib
-      shell: bash
-      run: |
-        mkdir -p /tmp/taglib
-        cd /tmp
-        FILE=taglib-${{ inputs.platform }}.tar.gz
-        wget https://github.com/navidrome/cross-taglib/releases/download/v${{ inputs.version }}/${FILE}
-        tar -xzf ${FILE} -C taglib
-        PKG_CONFIG_PREFIX=/tmp/taglib
-        echo "PKG_CONFIG_PREFIX=${PKG_CONFIG_PREFIX}" >> $GITHUB_ENV
-        echo "PKG_CONFIG_PATH=${PKG_CONFIG_PATH}:${PKG_CONFIG_PREFIX}/lib/pkgconfig" >> $GITHUB_ENV

.github/workflows/pipeline.yml

@@ -14,8 +14,6 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  CROSS_TAGLIB_VERSION: "2.2.0-1"
-  CGO_CFLAGS_ALLOW: "--define-prefix"
   IS_RELEASE: ${{ startsWith(github.ref, 'refs/tags/') && 'true' || 'false' }}
 
 jobs:
@@ -66,10 +64,9 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - name: Download TagLib
-        uses: ./.github/actions/download-taglib
+      - uses: actions/setup-go@v6
         with:
-          version: ${{ env.CROSS_TAGLIB_VERSION }}
+          go-version-file: go.mod
 
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v9
@@ -106,18 +103,15 @@ jobs:
       - name: Check out code into the Go module directory
         uses: actions/checkout@v6
 
-      - name: Download TagLib
-        uses: ./.github/actions/download-taglib
+      - uses: actions/setup-go@v6
         with:
-          version: ${{ env.CROSS_TAGLIB_VERSION }}
+          go-version-file: go.mod
 
       - name: Download dependencies
         run: go mod download
 
       - name: Test
-        run: |
-          pkg-config --define-prefix --cflags --libs taglib # for debugging
-          go test -shuffle=on -tags netgo,sqlite_fts5 -race ./... -v
+        run: go test -shuffle=on -tags netgo,sqlite_fts5 -race ./... -v
 
       - name: Test ndpgen
         run: |
@@ -126,6 +120,79 @@ jobs:
           go build -o ndpgen .
           ./ndpgen --help
 
+  go-windows:
+    name: Test Go code (Windows)
+    runs-on: windows-2022
+    env:
+      FFMPEG_VERSION: "7.1"
+      FFMPEG_REPOSITORY: navidrome/ffmpeg-windows-builds
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - uses: msys2/setup-msys2@v2
+        with:
+          msystem: MINGW64
+          install: mingw-w64-x86_64-gcc
+          update: false
+
+      - name: Add mingw64 to PATH
+        shell: bash
+        run: echo "C:/msys64/mingw64/bin" >> $GITHUB_PATH
+
+      - name: Cache ffmpeg
+        id: ffmpeg-cache
+        uses: actions/cache@v4
+        with:
+          path: C:\ffmpeg
+          key: ffmpeg-${{ env.FFMPEG_VERSION }}-win64
+
+      - name: Download ffmpeg
+        if: steps.ffmpeg-cache.outputs.cache-hit != 'true'
+        shell: pwsh
+        run: |
+          $asset = "ffmpeg-n${env:FFMPEG_VERSION}-latest-win64-gpl-${env:FFMPEG_VERSION}"
+          $url = "https://github.com/${env:FFMPEG_REPOSITORY}/releases/download/latest/$asset.zip"
+          Invoke-WebRequest -Uri $url -OutFile ffmpeg.zip
+          Expand-Archive ffmpeg.zip -DestinationPath C:\ffmpeg-extracted
+          New-Item -ItemType Directory -Force -Path C:\ffmpeg\bin | Out-Null
+          Copy-Item "C:\ffmpeg-extracted\$asset\bin\ffmpeg.exe"  C:\ffmpeg\bin
+          Copy-Item "C:\ffmpeg-extracted\$asset\bin\ffprobe.exe" C:\ffmpeg\bin
+
+      - name: Add ffmpeg to PATH
+        shell: bash
+        run: echo "C:/ffmpeg/bin" >> $GITHUB_PATH
+
+      - name: Verify toolchain
+        shell: pwsh
+        run: |
+          go version
+          where.exe gcc
+          gcc --version
+          ffmpeg -version
+          ffprobe -version
+
+      - name: Download dependencies
+        shell: bash
+        run: go mod download
+
+      - name: Test
+        shell: bash
+        env:
+          CGO_ENABLED: "1"
+        run: go test -shuffle=on -tags netgo,sqlite_fts5 ./... -v
+
+      - name: Test ndpgen
+        shell: pwsh
+        run: |
+          cd plugins\cmd\ndpgen
+          go test -shuffle=on -v
+          go build -o ndpgen.exe .
+          .\ndpgen.exe --help
+
   js:
     name: Test JS code
     runs-on: ubuntu-latest
@@ -190,7 +257,7 @@ jobs:
 
   build:
     name: Build
-    needs: [js, go, go-lint, i18n-lint, git-version, check-push-enabled]
+    needs: [js, go, go-windows, go-lint, i18n-lint, git-version, check-push-enabled]
     strategy:
       matrix:
         platform: [ linux/amd64, linux/arm64, linux/arm/v5, linux/arm/v6, linux/arm/v7, linux/386, linux/riscv64, darwin/amd64, darwin/arm64, windows/amd64, windows/386 ]
@@ -232,7 +299,6 @@ jobs:
           build-args: |
             GIT_SHA=${{ env.GIT_SHA }}
             GIT_TAG=${{ env.GIT_TAG }}
-            CROSS_TAGLIB_VERSION=${{ env.CROSS_TAGLIB_VERSION }}
 
       - name: Upload Binaries
         uses: actions/upload-artifact@v7
@@ -253,7 +319,6 @@ jobs:
           build-args: |
             GIT_SHA=${{ env.GIT_SHA }}
             GIT_TAG=${{ env.GIT_TAG }}
-            CROSS_TAGLIB_VERSION=${{ env.CROSS_TAGLIB_VERSION }}
           outputs: |
             type=image,name=${{ steps.docker.outputs.hub_repository }},push-by-digest=true,name-canonical=true,push=${{ steps.docker.outputs.hub_enabled }}
             type=image,name=ghcr.io/${{ github.repository }},push-by-digest=true,name-canonical=true,push=true

.golangci.yml

@@ -55,6 +55,7 @@ linters:
       - third_party$
       - builtin$
       - examples$
+      - node_modules
 formatters:
   exclusions:
     generated: lax
@@ -62,3 +63,4 @@ formatters:
       - third_party$
       - builtin$
       - examples$
+      - node_modules

Dockerfile

@@ -24,26 +24,6 @@ RUN cd /out && \
 FROM scratch AS xx
 COPY --from=xx-build /out/ /usr/bin/
 
-########################################################################################################################
-### Get TagLib
-FROM --platform=$BUILDPLATFORM public.ecr.aws/docker/library/alpine:3.20 AS taglib-build
-ARG TARGETPLATFORM
-ARG CROSS_TAGLIB_VERSION=2.2.0-1
-ENV CROSS_TAGLIB_RELEASES_URL=https://github.com/navidrome/cross-taglib/releases/download/v${CROSS_TAGLIB_VERSION}/
-
-# wget in busybox can't follow redirects
-RUN <<EOT
-    apk add --no-cache wget
-    PLATFORM=$(echo ${TARGETPLATFORM} | tr '/' '-')
-    FILE=taglib-${PLATFORM}.tar.gz
-
-    DOWNLOAD_URL=${CROSS_TAGLIB_RELEASES_URL}${FILE}
-    wget ${DOWNLOAD_URL}
-
-    mkdir /taglib
-    tar -xzf ${FILE} -C /taglib
-EOT
-
 ########################################################################################################################
 ### Build Navidrome UI
 FROM --platform=$BUILDPLATFORM public.ecr.aws/docker/library/node:lts-alpine AS ui
@@ -62,8 +42,47 @@ FROM scratch AS ui-bundle
 COPY --from=ui /build /build
 
 ########################################################################################################################
-### Build Navidrome binary
-FROM --platform=$BUILDPLATFORM public.ecr.aws/docker/library/golang:1.25-trixie AS base
+### Build Navidrome binary for Docker image (dynamic musl, enables native libwebp via dlopen)
+FROM --platform=$BUILDPLATFORM public.ecr.aws/docker/library/golang:1.26-alpine AS build-alpine
+COPY --from=xx / /
+
+ARG TARGETPLATFORM
+
+RUN apk add --no-cache clang lld file git
+RUN xx-apk add --no-cache gcc musl-dev zlib-dev
+RUN xx-verify --setup
+
+WORKDIR /workspace
+
+RUN --mount=type=bind,source=. \
+    --mount=type=cache,target=/root/.cache \
+    --mount=type=cache,target=/go/pkg/mod \
+    go mod download
+
+ARG GIT_SHA
+ARG GIT_TAG
+
+RUN --mount=type=bind,source=. \
+    --mount=from=ui,source=/build,target=./ui/build,ro \
+    --mount=type=cache,target=/root/.cache \
+    --mount=type=cache,target=/go/pkg/mod <<EOT
+    set -e
+    xx-go --wrap
+    export CGO_ENABLED=1
+    # -latomic is required on 32-bit arm (arm/v6, arm/v7) so SQLite's 64-bit atomics resolve.
+    go build -tags=netgo,sqlite_fts5 -ldflags="-w -s \
+        -linkmode=external -extldflags '-latomic' \
+        -X github.com/navidrome/navidrome/consts.gitSha=${GIT_SHA} \
+        -X github.com/navidrome/navidrome/consts.gitTag=${GIT_TAG}" \
+        -o /out/navidrome .
+    # Fail the build if the binary is accidentally statically linked: dlopen (and
+    # therefore native libwebp detection) only works with a dynamic interpreter.
+    file /out/navidrome | grep -q "dynamically linked" || { echo "ERROR: /out/navidrome is not dynamically linked"; file /out/navidrome; exit 1; }
+EOT
+
+########################################################################################################################
+### Build Navidrome binary for standalone distribution (static glibc, cross-compiled)
+FROM --platform=$BUILDPLATFORM public.ecr.aws/docker/library/golang:1.26-trixie AS base
 RUN apt-get update && apt-get install -y clang lld
 COPY --from=xx / /
 WORKDIR /workspace
@@ -88,14 +107,11 @@ RUN --mount=type=bind,source=. \
     --mount=from=ui,source=/build,target=./ui/build,ro \
     --mount=from=osxcross,src=/osxcross/SDK,target=/xx-sdk,ro \
     --mount=type=cache,target=/root/.cache \
-    --mount=type=cache,target=/go/pkg/mod \
-    --mount=from=taglib-build,target=/taglib,src=/taglib,ro <<EOT
+    --mount=type=cache,target=/go/pkg/mod <<EOT
 
     # Setup CGO cross-compilation environment
     xx-go --wrap
     export CGO_ENABLED=1
-    export CGO_CFLAGS_ALLOW="--define-prefix"
-    export PKG_CONFIG_PATH=/taglib/lib/pkgconfig
     cat $(go env GOENV)
 
     # Only Darwin (macOS) requires clang (default), Windows requires gcc, everything else can use any compiler.
@@ -127,21 +143,28 @@ FROM public.ecr.aws/docker/library/alpine:3.20 AS final
 LABEL maintainer="deluan@navidrome.org"
 LABEL org.opencontainers.image.source="https://github.com/navidrome/navidrome"
 
-# Install ffmpeg and mpv
-RUN apk add -U --no-cache ffmpeg mpv sqlite
+# Install runtime dependencies
+# - libwebp + symlinks: enables native WebP encoding via purego/dlopen
+RUN apk add -U --no-cache ffmpeg mpv sqlite libwebp libwebpdemux libwebpmux && \
+    for lib in libwebp libwebpdemux libwebpmux; do \
+        target=$(ls /usr/lib/$lib.so.* 2>/dev/null | head -1) && \
+        [ -n "$target" ] && ln -sf "$target" /usr/lib/$lib.so; \
+    done
 
-# Copy navidrome binary
-COPY --from=build /out/navidrome /app/
+# Copy navidrome binary (musl build for Docker, enables native libwebp)
+COPY --from=build-alpine /out/navidrome /app/
 
 VOLUME ["/data", "/music"]
 ENV ND_MUSICFOLDER=/music
 ENV ND_DATAFOLDER=/data
 ENV ND_CONFIGFILE=/data/navidrome.toml
 ENV ND_PORT=4533
+ENV ND_ENABLEWEBPENCODING=true
 RUN touch /.nddockerenv
 
 EXPOSE ${ND_PORT}
 WORKDIR /app
+ENV PATH="/app:${PATH}"
 
 ENTRYPOINT ["/app/navidrome"]
 

Makefile

@@ -1,9 +1,10 @@
 GO_VERSION=$(shell grep "^go " go.mod | cut -f 2 -d ' ')
 NODE_VERSION=$(shell cat .nvmrc)
-GO_BUILD_TAGS=netgo,sqlite_fts5
+
+comma:=,
+GO_BUILD_TAGS=netgo,sqlite_fts5$(if $(EXTRA_BUILD_TAGS),$(comma)$(EXTRA_BUILD_TAGS))
 
 # Set global environment variables, required for most targets
-export CGO_CFLAGS_ALLOW=--define-prefix
 export ND_ENABLEINSIGHTSCOLLECTOR=false
 
 ifneq ("$(wildcard .git/HEAD)","")
@@ -19,9 +20,7 @@ IMAGE_PLATFORMS ?= $(shell echo $(SUPPORTED_PLATFORMS) | tr ',' '\n' | grep "lin
 PLATFORMS ?= $(SUPPORTED_PLATFORMS)
 DOCKER_TAG ?= deluan/navidrome:develop
 
-# Taglib version to use in cross-compilation, from https://github.com/navidrome/cross-taglib
-CROSS_TAGLIB_VERSION ?= 2.2.1-1
-GOLANGCI_LINT_VERSION ?= v2.11.1
+GOLANGCI_LINT_VERSION ?= v2.12.0
 
 UI_SRC_FILES := $(shell find ui -type f -not -path "ui/build/*" -not -path "ui/node_modules/*")
 
@@ -76,8 +75,8 @@ test-i18n: ##@Development Validate all translations files
 
 install-golangci-lint: ##@Development Install golangci-lint if not present
 	@INSTALL=false; \
-	if PATH=$$PATH:./bin which golangci-lint > /dev/null 2>&1; then \
-		CURRENT_VERSION=$$(PATH=$$PATH:./bin golangci-lint version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1); \
+	if PATH=./bin:$$PATH which golangci-lint > /dev/null 2>&1; then \
+		CURRENT_VERSION=$$(PATH=./bin:$$PATH golangci-lint version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1); \
 		REQUIRED_VERSION=$$(echo "$(GOLANGCI_LINT_VERSION)" | sed 's/^v//'); \
 		if [ "$$CURRENT_VERSION" != "$$REQUIRED_VERSION" ]; then \
 			echo "Found golangci-lint $$CURRENT_VERSION, but $$REQUIRED_VERSION is required. Reinstalling..."; \
@@ -94,7 +93,7 @@ install-golangci-lint: ##@Development Install golangci-lint if not present
 .PHONY: install-golangci-lint
 
 lint: install-golangci-lint ##@Development Lint Go code
-	PATH=$$PATH:./bin golangci-lint run --timeout 5m
+	PATH=./bin:$$PATH golangci-lint run --timeout 5m
 .PHONY: lint
 
 lintall: lint ##@Development Lint Go and JS code
@@ -177,7 +176,6 @@ docker-build: ##@Cross_Compilation Cross-compile for any supported platform (che
 		--platform $(PLATFORMS) \
 		--build-arg GIT_TAG=${GIT_TAG} \
 		--build-arg GIT_SHA=${GIT_SHA} \
-		--build-arg CROSS_TAGLIB_VERSION=${CROSS_TAGLIB_VERSION} \
 		--output "./binaries" --target binary .
 .PHONY: docker-build
 
@@ -189,7 +187,6 @@ docker-image: ##@Cross_Compilation Build Docker image, tagged as `deluan/navidro
 		--platform $(IMAGE_PLATFORMS) \
 		--build-arg GIT_TAG=${GIT_TAG} \
 		--build-arg GIT_SHA=${GIT_SHA} \
-		--build-arg CROSS_TAGLIB_VERSION=${CROSS_TAGLIB_VERSION} \
 		--tag $(DOCKER_TAG) .
 .PHONY: docker-image
 

adapters/gotaglib/gotaglib_test.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"strings"
 
+	"github.com/navidrome/navidrome/tests"
 	"github.com/navidrome/navidrome/utils"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -127,6 +128,17 @@ var _ = Describe("Extractor", func() {
 				Expect(m.Tags).To(HaveKeyWithValue("albumartist", []string{"Album Artist"}))
 				Expect(m.Tags).To(HaveKeyWithValue("genre", []string{"Rock"}))
 				Expect(m.Tags).To(HaveKeyWithValue("date", []string{"2014"}))
+				// Still as of TagLib v2.2.1, TagLib only maps values in ID3, MP4, and ASF tags
+				// to `originaldate`.
+				if strings.HasSuffix(file, ".mp3") || strings.HasSuffix(file, ".wav") || strings.HasSuffix(file, ".aiff") || strings.HasSuffix(file, ".m4a") || strings.HasSuffix(file, ".wma") {
+					Expect(m.Tags).To(HaveKeyWithValue("originaldate", []string{"1996-11-21"}))
+				}
+				// MP3Tag sets `ORIGYEAR` in several formats for which it has no built-in mapping
+				// for original release dates.
+				Expect(m.Tags).To(Or(
+					HaveKeyWithValue("origyear", []string{"1998-07-28"}),
+					HaveKeyWithValue("----:com.apple.itunes:origyear", []string{"1998-07-28"}),
+				))
 
 				Expect(m.Tags).To(HaveKeyWithValue("bpm", []string{"123"}))
 				Expect(m.Tags).To(Or(
@@ -202,6 +214,7 @@ var _ = Describe("Extractor", func() {
 			// Only run permission tests if we are not root
 			RegularUserContext("when run without root privileges", func() {
 				BeforeEach(func() {
+					tests.SkipOnWindows("uses Unix file permission bits")
 					// Use root fs for absolute paths in temp directory
 					e = &extractor{fs: os.DirFS("/")}
 					accessForbiddenFile = utils.TempFileName("access_forbidden-", ".mp3")

adapters/lastfm/agent.go

@@ -416,6 +416,10 @@ func (l *lastfmAgent) IsAuthorized(ctx context.Context, userId string) bool {
 	return err == nil && sk != ""
 }
 
+func (l *lastfmAgent) PlaybackReport(context.Context, scrobbler.PlaybackSession) error {
+	return nil
+}
+
 func init() {
 	conf.AddHook(func() {
 		agents.Register(lastFMAgentName, func(ds model.DataStore) agents.Interface {

adapters/listenbrainz/agent.go

@@ -212,6 +212,10 @@ func (l *listenBrainzAgent) GetSimilarSongsByTrack(ctx context.Context, id strin
 	return songs, nil
 }
 
+func (l *listenBrainzAgent) PlaybackReport(context.Context, scrobbler.PlaybackSession) error {
+	return nil
+}
+
 func init() {
 	conf.AddHook(func() {
 		if conf.Server.ListenBrainz.Enabled {

adapters/taglib/end_to_end_test.go

@@ -1,274 +0,0 @@
-package taglib
-
-import (
-	"io/fs"
-	"os"
-	"time"
-
-	"github.com/djherbis/times"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/model/metadata"
-	"github.com/navidrome/navidrome/utils/gg"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-type testFileInfo struct {
-	fs.FileInfo
-}
-
-func (t testFileInfo) BirthTime() time.Time {
-	if ts := times.Get(t.FileInfo); ts.HasBirthTime() {
-		return ts.BirthTime()
-	}
-	return t.FileInfo.ModTime()
-}
-
-var _ = Describe("Extractor", func() {
-	toP := func(name, sortName, mbid string) model.Participant {
-		return model.Participant{
-			Artist: model.Artist{Name: name, SortArtistName: sortName, MbzArtistID: mbid},
-		}
-	}
-
-	roles := []struct {
-		model.Role
-		model.ParticipantList
-	}{
-		{model.RoleComposer, model.ParticipantList{
-			toP("coma a", "a, coma", "bf13b584-f27c-43db-8f42-32898d33d4e2"),
-			toP("comb", "comb", "924039a2-09c6-4d29-9b4f-50cc54447d36"),
-		}},
-		{model.RoleLyricist, model.ParticipantList{
-			toP("la a", "a, la", "c84f648f-68a6-40a2-a0cb-d135b25da3c2"),
-			toP("lb", "lb", "0a7c582d-143a-4540-b4e9-77200835af65"),
-		}},
-		{model.RoleArranger, model.ParticipantList{
-			toP("aa", "", "4605a1d4-8d15-42a3-bd00-9c20e42f71e6"),
-			toP("ab", "", "002f0ff8-77bf-42cc-8216-61a9c43dc145"),
-		}},
-		{model.RoleConductor, model.ParticipantList{
-			toP("cona", "", "af86879b-2141-42af-bad2-389a4dc91489"),
-			toP("conb", "", "3dfa3c70-d7d3-4b97-b953-c298dd305e12"),
-		}},
-		{model.RoleDirector, model.ParticipantList{
-			toP("dia", "", "f943187f-73de-4794-be47-88c66f0fd0f4"),
-			toP("dib", "", "bceb75da-1853-4b3d-b399-b27f0cafc389"),
-		}},
-		{model.RoleEngineer, model.ParticipantList{
-			toP("ea", "", "f634bf6d-d66a-425d-888a-28ad39392759"),
-			toP("eb", "", "243d64ae-d514-44e1-901a-b918d692baee"),
-		}},
-		{model.RoleProducer, model.ParticipantList{
-			toP("pra", "", "d971c8d7-999c-4a5f-ac31-719721ab35d6"),
-			toP("prb", "", "f0a09070-9324-434f-a599-6d25ded87b69"),
-		}},
-		{model.RoleRemixer, model.ParticipantList{
-			toP("ra", "", "c7dc6095-9534-4c72-87cc-aea0103462cf"),
-			toP("rb", "", "8ebeef51-c08c-4736-992f-c37870becedd"),
-		}},
-		{model.RoleDJMixer, model.ParticipantList{
-			toP("dja", "", "d063f13b-7589-4efc-ab7f-c60e6db17247"),
-			toP("djb", "", "3636670c-385f-4212-89c8-0ff51d6bc456"),
-		}},
-		{model.RoleMixer, model.ParticipantList{
-			toP("ma", "", "53fb5a2d-7016-427e-a563-d91819a5f35a"),
-			toP("mb", "", "64c13e65-f0da-4ab9-a300-71ee53b0376a"),
-		}},
-	}
-
-	var e *extractor
-
-	parseTestFile := func(path string) *model.MediaFile {
-		mds, err := e.Parse(path)
-		Expect(err).ToNot(HaveOccurred())
-
-		info, ok := mds[path]
-		Expect(ok).To(BeTrue())
-
-		fileInfo, err := os.Stat(path)
-		Expect(err).ToNot(HaveOccurred())
-		info.FileInfo = testFileInfo{FileInfo: fileInfo}
-
-		metadata := metadata.New(path, info)
-		mf := metadata.ToMediaFile(1, "folderID")
-		return &mf
-	}
-
-	BeforeEach(func() {
-		e = &extractor{}
-	})
-
-	Describe("ReplayGain", func() {
-		DescribeTable("test replaygain end-to-end", func(file string, trackGain, trackPeak, albumGain, albumPeak *float64) {
-			mf := parseTestFile("tests/fixtures/" + file)
-
-			Expect(mf.RGTrackGain).To(Equal(trackGain))
-			Expect(mf.RGTrackPeak).To(Equal(trackPeak))
-			Expect(mf.RGAlbumGain).To(Equal(albumGain))
-			Expect(mf.RGAlbumPeak).To(Equal(albumPeak))
-		},
-			Entry("mp3 with no replaygain", "no_replaygain.mp3", nil, nil, nil, nil),
-			Entry("mp3 with no zero replaygain", "zero_replaygain.mp3", gg.P(0.0), gg.P(1.0), gg.P(0.0), gg.P(1.0)),
-		)
-	})
-
-	Describe("lyrics", func() {
-		makeLyrics := func(code, secondLine string) model.Lyrics {
-			return model.Lyrics{
-				DisplayArtist: "",
-				DisplayTitle:  "",
-				Lang:          code,
-				Line: []model.Line{
-					{Start: gg.P(int64(0)), Value: "This is"},
-					{Start: gg.P(int64(2500)), Value: secondLine},
-				},
-				Offset: nil,
-				Synced: true,
-			}
-		}
-
-		It("should fetch both synced and unsynced lyrics in mixed flac", func() {
-			mf := parseTestFile("tests/fixtures/mixed-lyrics.flac")
-
-			lyrics, err := mf.StructuredLyrics()
-			Expect(err).ToNot(HaveOccurred())
-			Expect(lyrics).To(HaveLen(2))
-
-			Expect(lyrics[0].Synced).To(BeTrue())
-			Expect(lyrics[1].Synced).To(BeFalse())
-		})
-
-		It("should handle mp3 with uslt and sylt", func() {
-			mf := parseTestFile("tests/fixtures/test.mp3")
-
-			lyrics, err := mf.StructuredLyrics()
-			Expect(err).ToNot(HaveOccurred())
-			Expect(lyrics).To(HaveLen(4))
-
-			engSylt := makeLyrics("eng", "English SYLT")
-			engUslt := makeLyrics("eng", "English")
-			unsSylt := makeLyrics("xxx", "unspecified SYLT")
-			unsUslt := makeLyrics("xxx", "unspecified")
-
-			Expect(lyrics).To(ConsistOf(engSylt, engUslt, unsSylt, unsUslt))
-		})
-
-		DescribeTable("format-specific lyrics", func(file string, isId3 bool) {
-			mf := parseTestFile("tests/fixtures/" + file)
-
-			lyrics, err := mf.StructuredLyrics()
-			Expect(err).To(Not(HaveOccurred()))
-			Expect(lyrics).To(HaveLen(2))
-
-			unspec := makeLyrics("xxx", "unspecified")
-			eng := makeLyrics("xxx", "English")
-
-			if isId3 {
-				eng.Lang = "eng"
-			}
-
-			Expect(lyrics).To(Or(
-				Equal(model.LyricList{unspec, eng}),
-				Equal(model.LyricList{eng, unspec})))
-		},
-			Entry("flac", "test.flac", false),
-			Entry("m4a", "test.m4a", false),
-			Entry("ogg", "test.ogg", false),
-			Entry("wma", "test.wma", false),
-			Entry("wv", "test.wv", false),
-			Entry("wav", "test.wav", true),
-			Entry("aiff", "test.aiff", true),
-		)
-	})
-
-	Describe("Participants", func() {
-		DescribeTable("test tags consistent across formats", func(format string) {
-			mf := parseTestFile("tests/fixtures/test." + format)
-
-			for _, data := range roles {
-				role := data.Role
-				artists := data.ParticipantList
-
-				actual := mf.Participants[role]
-				Expect(actual).To(HaveLen(len(artists)))
-
-				for i := range artists {
-					actualArtist := actual[i]
-					expectedArtist := artists[i]
-
-					Expect(actualArtist.Name).To(Equal(expectedArtist.Name))
-					Expect(actualArtist.SortArtistName).To(Equal(expectedArtist.SortArtistName))
-					Expect(actualArtist.MbzArtistID).To(Equal(expectedArtist.MbzArtistID))
-				}
-			}
-
-			if format != "m4a" {
-				performers := mf.Participants[model.RolePerformer]
-				Expect(performers).To(HaveLen(8))
-
-				rules := map[string][]string{
-					"pgaa": {"2fd0b311-9fa8-4ff9-be5d-f6f3d16b835e", "Guitar"},
-					"pgbb": {"223d030b-bf97-4c2a-ad26-b7f7bbe25c93", "Guitar", ""},
-					"pvaa": {"cb195f72-448f-41c8-b962-3f3c13d09d38", "Vocals"},
-					"pvbb": {"60a1f832-8ca2-49f6-8660-84d57f07b520", "Vocals", "Flute"},
-					"pfaa": {"51fb40c-0305-4bf9-a11b-2ee615277725", "", "Flute"},
-				}
-
-				for name, rule := range rules {
-					mbid := rule[0]
-					for i := 1; i < len(rule); i++ {
-						found := false
-
-						for _, mapped := range performers {
-							if mapped.Name == name && mapped.MbzArtistID == mbid && mapped.SubRole == rule[i] {
-								found = true
-								break
-							}
-						}
-
-						Expect(found).To(BeTrue(), "Could not find matching artist")
-					}
-				}
-			}
-		},
-			Entry("FLAC format", "flac"),
-			Entry("M4a format", "m4a"),
-			Entry("OGG format", "ogg"),
-			Entry("WV format", "wv"),
-
-			Entry("MP3 format", "mp3"),
-			Entry("WAV format", "wav"),
-			Entry("AIFF format", "aiff"),
-		)
-
-		It("should parse wma", func() {
-			mf := parseTestFile("tests/fixtures/test.wma")
-
-			for _, data := range roles {
-				role := data.Role
-				artists := data.ParticipantList
-				actual := mf.Participants[role]
-
-				// WMA has no Arranger role
-				if role == model.RoleArranger {
-					Expect(actual).To(HaveLen(0))
-					continue
-				}
-
-				Expect(actual).To(HaveLen(len(artists)), role.String())
-
-				// For some bizarre reason, the order is inverted. We also don't get
-				// sort names or MBIDs
-				for i := range artists {
-					idx := len(artists) - 1 - i
-
-					actualArtist := actual[i]
-					expectedArtist := artists[idx]
-
-					Expect(actualArtist.Name).To(Equal(expectedArtist.Name))
-				}
-			}
-		})
-	})
-})

adapters/taglib/get_filename.go

@@ -1,9 +0,0 @@
-//go:build !windows
-
-package taglib
-
-import "C"
-
-func getFilename(s string) *C.char {
-	return C.CString(s)
-}

adapters/taglib/get_filename_win.go

@@ -1,96 +0,0 @@
-//go:build windows
-
-package taglib
-
-// From https://github.com/orofarne/gowchar
-
-/*
-#include <wchar.h>
-
-const size_t SIZEOF_WCHAR_T = sizeof(wchar_t);
-
-void gowchar_set (wchar_t *arr, int pos, wchar_t val)
-{
-	arr[pos] = val;
-}
-
-wchar_t gowchar_get (wchar_t *arr, int pos)
-{
-	return arr[pos];
-}
-*/
-import "C"
-
-import (
-	"fmt"
-	"unicode/utf16"
-	"unicode/utf8"
-)
-
-var SIZEOF_WCHAR_T C.size_t = C.size_t(C.SIZEOF_WCHAR_T)
-
-func getFilename(s string) *C.wchar_t {
-	wstr, _ := StringToWcharT(s)
-	return wstr
-}
-
-func StringToWcharT(s string) (*C.wchar_t, C.size_t) {
-	switch SIZEOF_WCHAR_T {
-	case 2:
-		return stringToWchar2(s) // Windows
-	case 4:
-		return stringToWchar4(s) // Unix
-	default:
-		panic(fmt.Sprintf("Invalid sizeof(wchar_t) = %v", SIZEOF_WCHAR_T))
-	}
-	panic("?!!")
-}
-
-// Windows
-func stringToWchar2(s string) (*C.wchar_t, C.size_t) {
-	var slen int
-	s1 := s
-	for len(s1) > 0 {
-		r, size := utf8.DecodeRuneInString(s1)
-		if er, _ := utf16.EncodeRune(r); er == '\uFFFD' {
-			slen += 1
-		} else {
-			slen += 2
-		}
-		s1 = s1[size:]
-	}
-	slen++ // \0
-	res := C.malloc(C.size_t(slen) * SIZEOF_WCHAR_T)
-	var i int
-	for len(s) > 0 {
-		r, size := utf8.DecodeRuneInString(s)
-		if r1, r2 := utf16.EncodeRune(r); r1 != '\uFFFD' {
-			C.gowchar_set((*C.wchar_t)(res), C.int(i), C.wchar_t(r1))
-			i++
-			C.gowchar_set((*C.wchar_t)(res), C.int(i), C.wchar_t(r2))
-			i++
-		} else {
-			C.gowchar_set((*C.wchar_t)(res), C.int(i), C.wchar_t(r))
-			i++
-		}
-		s = s[size:]
-	}
-	C.gowchar_set((*C.wchar_t)(res), C.int(slen-1), C.wchar_t(0)) // \0
-	return (*C.wchar_t)(res), C.size_t(slen)
-}
-
-// Unix
-func stringToWchar4(s string) (*C.wchar_t, C.size_t) {
-	slen := utf8.RuneCountInString(s)
-	slen++ // \0
-	res := C.malloc(C.size_t(slen) * SIZEOF_WCHAR_T)
-	var i int
-	for len(s) > 0 {
-		r, size := utf8.DecodeRuneInString(s)
-		C.gowchar_set((*C.wchar_t)(res), C.int(i), C.wchar_t(r))
-		s = s[size:]
-		i++
-	}
-	C.gowchar_set((*C.wchar_t)(res), C.int(slen-1), C.wchar_t(0)) // \0
-	return (*C.wchar_t)(res), C.size_t(slen)
-}

adapters/taglib/taglib.go

@@ -1,178 +0,0 @@
-package taglib
-
-import (
-	"io/fs"
-	"path/filepath"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core/storage/local"
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/model/metadata"
-)
-
-type extractor struct {
-	baseDir string
-}
-
-func (e extractor) Parse(files ...string) (map[string]metadata.Info, error) {
-	results := make(map[string]metadata.Info)
-	for _, path := range files {
-		props, err := e.extractMetadata(path)
-		if err != nil {
-			continue
-		}
-		results[path] = *props
-	}
-	return results, nil
-}
-
-func (e extractor) Version() string {
-	return Version()
-}
-
-func (e extractor) extractMetadata(filePath string) (*metadata.Info, error) {
-	fullPath := filepath.Join(e.baseDir, filePath)
-	tags, err := Read(fullPath)
-	if err != nil {
-		log.Warn("extractor: Error reading metadata from file. Skipping", "filePath", fullPath, err)
-		return nil, err
-	}
-
-	// Parse audio properties
-	ap := metadata.AudioProperties{}
-	ap.BitRate = parseProp(tags, "__bitrate")
-	ap.Channels = parseProp(tags, "__channels")
-	ap.SampleRate = parseProp(tags, "__samplerate")
-	ap.BitDepth = parseProp(tags, "__bitspersample")
-	length := parseProp(tags, "__lengthinmilliseconds")
-	ap.Duration = (time.Millisecond * time.Duration(length)).Round(time.Millisecond * 10)
-
-	// Extract basic tags
-	parseBasicTag(tags, "__title", "title")
-	parseBasicTag(tags, "__artist", "artist")
-	parseBasicTag(tags, "__album", "album")
-	parseBasicTag(tags, "__comment", "comment")
-	parseBasicTag(tags, "__genre", "genre")
-	parseBasicTag(tags, "__year", "year")
-	parseBasicTag(tags, "__track", "tracknumber")
-
-	// Parse track/disc totals
-	parseTuple := func(prop string) {
-		tagName := prop + "number"
-		tagTotal := prop + "total"
-		if value, ok := tags[tagName]; ok && len(value) > 0 {
-			parts := strings.Split(value[0], "/")
-			tags[tagName] = []string{parts[0]}
-			if len(parts) == 2 {
-				tags[tagTotal] = []string{parts[1]}
-			}
-		}
-	}
-	parseTuple("track")
-	parseTuple("disc")
-
-	// Adjust some ID3 tags
-	parseLyrics(tags)
-	parseTIPL(tags)
-	delete(tags, "tmcl") // TMCL is already parsed by TagLib
-
-	return &metadata.Info{
-		Tags:            tags,
-		AudioProperties: ap,
-		HasPicture:      tags["has_picture"] != nil && len(tags["has_picture"]) > 0 && tags["has_picture"][0] == "true",
-	}, nil
-}
-
-// parseLyrics make sure lyrics tags have language
-func parseLyrics(tags map[string][]string) {
-	lyrics := tags["lyrics"]
-	if len(lyrics) > 0 {
-		tags["lyrics:xxx"] = lyrics
-		delete(tags, "lyrics")
-	}
-}
-
-// These are the only roles we support, based on Picard's tag map:
-// https://picard-docs.musicbrainz.org/downloads/MusicBrainz_Picard_Tag_Map.html
-var tiplMapping = map[string]string{
-	"arranger": "arranger",
-	"engineer": "engineer",
-	"producer": "producer",
-	"mix":      "mixer",
-	"DJ-mix":   "djmixer",
-}
-
-// parseProp parses a property from the tags map and sets it to the target integer.
-// It also deletes the property from the tags map after parsing.
-func parseProp(tags map[string][]string, prop string) int {
-	if value, ok := tags[prop]; ok && len(value) > 0 {
-		v, _ := strconv.Atoi(value[0])
-		delete(tags, prop)
-		return v
-	}
-	return 0
-}
-
-// parseBasicTag checks if a basic tag (like __title, __artist, etc.) exists in the tags map.
-// If it does, it moves the value to a more appropriate tag name (like title, artist, etc.),
-// and deletes the basic tag from the map. If the target tag already exists, it ignores the basic tag.
-func parseBasicTag(tags map[string][]string, basicName string, tagName string) {
-	basicValue := tags[basicName]
-	if len(basicValue) == 0 {
-		return
-	}
-	delete(tags, basicName)
-	if len(tags[tagName]) == 0 {
-		tags[tagName] = basicValue
-	}
-}
-
-// parseTIPL parses the ID3v2.4 TIPL frame string, which is received from TagLib in the format:
-//
-//	"arranger Andrew Powell engineer Chris Blair engineer Pat Stapley producer Eric Woolfson".
-//
-// and breaks it down into a map of roles and names, e.g.:
-//
-//	{"arranger": ["Andrew Powell"], "engineer": ["Chris Blair", "Pat Stapley"], "producer": ["Eric Woolfson"]}.
-func parseTIPL(tags map[string][]string) {
-	tipl := tags["tipl"]
-	if len(tipl) == 0 {
-		return
-	}
-
-	addRole := func(currentRole string, currentValue []string) {
-		if currentRole != "" && len(currentValue) > 0 {
-			role := tiplMapping[currentRole]
-			tags[role] = append(tags[role], strings.Join(currentValue, " "))
-		}
-	}
-
-	var currentRole string
-	var currentValue []string
-	for _, part := range strings.Split(tipl[0], " ") {
-		if _, ok := tiplMapping[part]; ok {
-			addRole(currentRole, currentValue)
-			currentRole = part
-			currentValue = nil
-			continue
-		}
-		currentValue = append(currentValue, part)
-	}
-	addRole(currentRole, currentValue)
-	delete(tags, "tipl")
-}
-
-var _ local.Extractor = (*extractor)(nil)
-
-func init() {
-	local.RegisterExtractor("legacy-taglib", func(_ fs.FS, baseDir string) local.Extractor {
-		// ignores fs, as taglib extractor only works with local files
-		return &extractor{baseDir}
-	})
-	conf.AddHook(func() {
-		log.Debug("TagLib version", "version", Version())
-	})
-}

adapters/taglib/taglib_test.go

@@ -1,295 +0,0 @@
-package taglib
-
-import (
-	"io/fs"
-	"os"
-	"strings"
-
-	"github.com/navidrome/navidrome/utils"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Extractor", func() {
-	var e *extractor
-
-	BeforeEach(func() {
-		e = &extractor{}
-	})
-
-	Describe("Parse", func() {
-		It("correctly parses metadata from all files in folder", func() {
-			mds, err := e.Parse(
-				"tests/fixtures/test.mp3",
-				"tests/fixtures/test.ogg",
-			)
-			Expect(err).NotTo(HaveOccurred())
-			Expect(mds).To(HaveLen(2))
-
-			// Test MP3
-			m := mds["tests/fixtures/test.mp3"]
-			Expect(m.Tags).To(HaveKeyWithValue("title", []string{"Song"}))
-			Expect(m.Tags).To(HaveKeyWithValue("album", []string{"Album"}))
-			Expect(m.Tags).To(HaveKeyWithValue("artist", []string{"Artist"}))
-			Expect(m.Tags).To(HaveKeyWithValue("albumartist", []string{"Album Artist"}))
-
-			Expect(m.HasPicture).To(BeTrue())
-			Expect(m.AudioProperties.Duration.String()).To(Equal("1.02s"))
-			Expect(m.AudioProperties.BitRate).To(Equal(192))
-			Expect(m.AudioProperties.Channels).To(Equal(2))
-			Expect(m.AudioProperties.SampleRate).To(Equal(44100))
-
-			Expect(m.Tags).To(Or(
-				HaveKeyWithValue("compilation", []string{"1"}),
-				HaveKeyWithValue("tcmp", []string{"1"})),
-			)
-			Expect(m.Tags).To(HaveKeyWithValue("genre", []string{"Rock"}))
-			Expect(m.Tags).To(HaveKeyWithValue("date", []string{"2014-05-21"}))
-			Expect(m.Tags).To(HaveKeyWithValue("originaldate", []string{"1996-11-21"}))
-			Expect(m.Tags).To(HaveKeyWithValue("releasedate", []string{"2020-12-31"}))
-			Expect(m.Tags).To(HaveKeyWithValue("discnumber", []string{"1"}))
-			Expect(m.Tags).To(HaveKeyWithValue("disctotal", []string{"2"}))
-			Expect(m.Tags).To(HaveKeyWithValue("comment", []string{"Comment1\nComment2"}))
-			Expect(m.Tags).To(HaveKeyWithValue("bpm", []string{"123"}))
-			Expect(m.Tags).To(HaveKeyWithValue("replaygain_album_gain", []string{"+3.21518 dB"}))
-			Expect(m.Tags).To(HaveKeyWithValue("replaygain_album_peak", []string{"0.9125"}))
-			Expect(m.Tags).To(HaveKeyWithValue("replaygain_track_gain", []string{"-1.48 dB"}))
-			Expect(m.Tags).To(HaveKeyWithValue("replaygain_track_peak", []string{"0.4512"}))
-
-			Expect(m.Tags).To(HaveKeyWithValue("tracknumber", []string{"2"}))
-			Expect(m.Tags).To(HaveKeyWithValue("tracktotal", []string{"10"}))
-
-			Expect(m.Tags).ToNot(HaveKey("lyrics"))
-			Expect(m.Tags).To(Or(HaveKeyWithValue("lyrics:eng", []string{
-				"[00:00.00]This is\n[00:02.50]English SYLT\n",
-				"[00:00.00]This is\n[00:02.50]English",
-			}), HaveKeyWithValue("lyrics:eng", []string{
-				"[00:00.00]This is\n[00:02.50]English",
-				"[00:00.00]This is\n[00:02.50]English SYLT\n",
-			})))
-			Expect(m.Tags).To(Or(HaveKeyWithValue("lyrics:xxx", []string{
-				"[00:00.00]This is\n[00:02.50]unspecified SYLT\n",
-				"[00:00.00]This is\n[00:02.50]unspecified",
-			}), HaveKeyWithValue("lyrics:xxx", []string{
-				"[00:00.00]This is\n[00:02.50]unspecified",
-				"[00:00.00]This is\n[00:02.50]unspecified SYLT\n",
-			})))
-
-			// Test OGG
-			m = mds["tests/fixtures/test.ogg"]
-			Expect(err).To(BeNil())
-			Expect(m.Tags).To(HaveKeyWithValue("fbpm", []string{"141.7"}))
-
-			// TagLib 1.12 returns 18, previous versions return 39.
-			// See https://github.com/taglib/taglib/commit/2f238921824741b2cfe6fbfbfc9701d9827ab06b
-			Expect(m.AudioProperties.BitRate).To(BeElementOf(18, 19, 39, 40, 43, 49))
-			Expect(m.AudioProperties.Channels).To(BeElementOf(2))
-			Expect(m.AudioProperties.SampleRate).To(BeElementOf(8000))
-			Expect(m.HasPicture).To(BeTrue())
-		})
-
-		DescribeTable("Format-Specific tests",
-			func(file, duration string, channels, samplerate, bitdepth int, albumGain, albumPeak, trackGain, trackPeak string, id3Lyrics bool, image bool) {
-				file = "tests/fixtures/" + file
-				mds, err := e.Parse(file)
-				Expect(err).NotTo(HaveOccurred())
-				Expect(mds).To(HaveLen(1))
-
-				m := mds[file]
-
-				Expect(m.HasPicture).To(Equal(image))
-				Expect(m.AudioProperties.Duration.String()).To(Equal(duration))
-				Expect(m.AudioProperties.Channels).To(Equal(channels))
-				Expect(m.AudioProperties.SampleRate).To(Equal(samplerate))
-				Expect(m.AudioProperties.BitDepth).To(Equal(bitdepth))
-
-				Expect(m.Tags).To(Or(
-					HaveKeyWithValue("replaygain_album_gain", []string{albumGain}),
-					HaveKeyWithValue("----:com.apple.itunes:replaygain_album_gain", []string{albumGain}),
-				))
-
-				Expect(m.Tags).To(Or(
-					HaveKeyWithValue("replaygain_album_peak", []string{albumPeak}),
-					HaveKeyWithValue("----:com.apple.itunes:replaygain_album_peak", []string{albumPeak}),
-				))
-				Expect(m.Tags).To(Or(
-					HaveKeyWithValue("replaygain_track_gain", []string{trackGain}),
-					HaveKeyWithValue("----:com.apple.itunes:replaygain_track_gain", []string{trackGain}),
-				))
-				Expect(m.Tags).To(Or(
-					HaveKeyWithValue("replaygain_track_peak", []string{trackPeak}),
-					HaveKeyWithValue("----:com.apple.itunes:replaygain_track_peak", []string{trackPeak}),
-				))
-
-				Expect(m.Tags).To(HaveKeyWithValue("title", []string{"Title"}))
-				Expect(m.Tags).To(HaveKeyWithValue("album", []string{"Album"}))
-				Expect(m.Tags).To(HaveKeyWithValue("artist", []string{"Artist"}))
-				Expect(m.Tags).To(HaveKeyWithValue("albumartist", []string{"Album Artist"}))
-				Expect(m.Tags).To(HaveKeyWithValue("genre", []string{"Rock"}))
-				Expect(m.Tags).To(HaveKeyWithValue("date", []string{"2014"}))
-
-				Expect(m.Tags).To(HaveKeyWithValue("bpm", []string{"123"}))
-				Expect(m.Tags).To(Or(
-					HaveKeyWithValue("tracknumber", []string{"3"}),
-					HaveKeyWithValue("tracknumber", []string{"3/10"}),
-				))
-				if !strings.HasSuffix(file, "test.wma") {
-					// TODO Not sure why this is not working for WMA
-					Expect(m.Tags).To(HaveKeyWithValue("tracktotal", []string{"10"}))
-				}
-				Expect(m.Tags).To(Or(
-					HaveKeyWithValue("discnumber", []string{"1"}),
-					HaveKeyWithValue("discnumber", []string{"1/2"}),
-				))
-				Expect(m.Tags).To(HaveKeyWithValue("disctotal", []string{"2"}))
-
-				// WMA does not have a "compilation" tag, but "wm/iscompilation"
-				Expect(m.Tags).To(Or(
-					HaveKeyWithValue("compilation", []string{"1"}),
-					HaveKeyWithValue("wm/iscompilation", []string{"1"})),
-				)
-
-				if id3Lyrics {
-					Expect(m.Tags).To(HaveKeyWithValue("lyrics:eng", []string{
-						"[00:00.00]This is\n[00:02.50]English",
-					}))
-					Expect(m.Tags).To(HaveKeyWithValue("lyrics:xxx", []string{
-						"[00:00.00]This is\n[00:02.50]unspecified",
-					}))
-				} else {
-					Expect(m.Tags).To(HaveKeyWithValue("lyrics:xxx", []string{
-						"[00:00.00]This is\n[00:02.50]unspecified",
-						"[00:00.00]This is\n[00:02.50]English",
-					}))
-				}
-
-				Expect(m.Tags).To(HaveKeyWithValue("comment", []string{"Comment1\nComment2"}))
-			},
-
-			// ffmpeg -f lavfi -i "sine=frequency=1200:duration=1" test.flac
-			Entry("correctly parses flac tags", "test.flac", "1s", 1, 44100, 16, "+4.06 dB", "0.12496948", "+4.06 dB", "0.12496948", false, true),
-
-			Entry("correctly parses m4a (aac) gain tags", "01 Invisible (RED) Edit Version.m4a", "1.04s", 2, 44100, 16, "0.37", "0.48", "0.37", "0.48", false, true),
-			Entry("correctly parses m4a (aac) gain tags (uppercase)", "test.m4a", "1.04s", 2, 44100, 16, "0.37", "0.48", "0.37", "0.48", false, true),
-			Entry("correctly parses ogg (vorbis) tags", "test.ogg", "1.04s", 2, 8000, 0, "+7.64 dB", "0.11772506", "+7.64 dB", "0.11772506", false, true),
-
-			// ffmpeg -f lavfi -i "sine=frequency=900:duration=1" test.wma
-			// Weird note: for the tag parsing to work, the lyrics are actually stored in the reverse order
-			Entry("correctly parses wma/asf tags", "test.wma", "1.02s", 1, 44100, 16, "3.27 dB", "0.132914", "3.27 dB", "0.132914", false, true),
-
-			// ffmpeg -f lavfi -i "sine=frequency=800:duration=1" test.wv
-			Entry("correctly parses wv (wavpak) tags", "test.wv", "1s", 1, 44100, 16, "3.43 dB", "0.125061", "3.43 dB", "0.125061", false, true),
-
-			// ffmpeg -f lavfi -i "sine=frequency=1000:duration=1" test.wav
-			Entry("correctly parses wav tags", "test.wav", "1s", 1, 44100, 16, "3.06 dB", "0.125056", "3.06 dB", "0.125056", true, true),
-
-			// ffmpeg -f lavfi -i "sine=frequency=1400:duration=1" test.aiff
-			Entry("correctly parses aiff tags", "test.aiff", "1s", 1, 44100, 16, "2.00 dB", "0.124972", "2.00 dB", "0.124972", true, true),
-		)
-
-		// Skip these tests when running as root
-		Context("Access Forbidden", func() {
-			var accessForbiddenFile string
-			var RegularUserContext = XContext
-			var isRegularUser = os.Getuid() != 0
-			if isRegularUser {
-				RegularUserContext = Context
-			}
-
-			// Only run permission tests if we are not root
-			RegularUserContext("when run without root privileges", func() {
-				BeforeEach(func() {
-					accessForbiddenFile = utils.TempFileName("access_forbidden-", ".mp3")
-
-					f, err := os.OpenFile(accessForbiddenFile, os.O_WRONLY|os.O_CREATE, 0222)
-					Expect(err).ToNot(HaveOccurred())
-
-					DeferCleanup(func() {
-						Expect(f.Close()).To(Succeed())
-						Expect(os.Remove(accessForbiddenFile)).To(Succeed())
-					})
-				})
-
-				It("correctly handle unreadable file due to insufficient read permission", func() {
-					_, err := e.extractMetadata(accessForbiddenFile)
-					Expect(err).To(MatchError(os.ErrPermission))
-				})
-
-				It("skips the file if it cannot be read", func() {
-					files := []string{
-						"tests/fixtures/test.mp3",
-						"tests/fixtures/test.ogg",
-						accessForbiddenFile,
-					}
-					mds, err := e.Parse(files...)
-					Expect(err).NotTo(HaveOccurred())
-					Expect(mds).To(HaveLen(2))
-					Expect(mds).ToNot(HaveKey(accessForbiddenFile))
-				})
-			})
-		})
-
-	})
-
-	Describe("Error Checking", func() {
-		It("returns a generic ErrPath if file does not exist", func() {
-			testFilePath := "tests/fixtures/NON_EXISTENT.ogg"
-			_, err := e.extractMetadata(testFilePath)
-			Expect(err).To(MatchError(fs.ErrNotExist))
-		})
-		It("does not throw a SIGSEGV error when reading a file with an invalid frame", func() {
-			// File has an empty TDAT frame
-			md, err := e.extractMetadata("tests/fixtures/invalid-files/test-invalid-frame.mp3")
-			Expect(err).ToNot(HaveOccurred())
-			Expect(md.Tags).To(HaveKeyWithValue("albumartist", []string{"Elvis Presley"}))
-		})
-	})
-
-	Describe("parseTIPL", func() {
-		var tags map[string][]string
-
-		BeforeEach(func() {
-			tags = make(map[string][]string)
-		})
-
-		Context("when the TIPL string is populated", func() {
-			It("correctly parses roles and names", func() {
-				tags["tipl"] = []string{"arranger Andrew Powell DJ-mix François Kevorkian DJ-mix Jane Doe engineer Chris Blair"}
-				parseTIPL(tags)
-				Expect(tags["arranger"]).To(ConsistOf("Andrew Powell"))
-				Expect(tags["engineer"]).To(ConsistOf("Chris Blair"))
-				Expect(tags["djmixer"]).To(ConsistOf("François Kevorkian", "Jane Doe"))
-			})
-
-			It("handles multiple names for a single role", func() {
-				tags["tipl"] = []string{"engineer Pat Stapley producer Eric Woolfson engineer Chris Blair"}
-				parseTIPL(tags)
-				Expect(tags["producer"]).To(ConsistOf("Eric Woolfson"))
-				Expect(tags["engineer"]).To(ConsistOf("Pat Stapley", "Chris Blair"))
-			})
-
-			It("discards roles without names", func() {
-				tags["tipl"] = []string{"engineer Pat Stapley producer engineer Chris Blair"}
-				parseTIPL(tags)
-				Expect(tags).ToNot(HaveKey("producer"))
-				Expect(tags["engineer"]).To(ConsistOf("Pat Stapley", "Chris Blair"))
-			})
-		})
-
-		Context("when the TIPL string is empty", func() {
-			It("does nothing", func() {
-				tags["tipl"] = []string{""}
-				parseTIPL(tags)
-				Expect(tags).To(BeEmpty())
-			})
-		})
-
-		Context("when the TIPL is not present", func() {
-			It("does nothing", func() {
-				parseTIPL(tags)
-				Expect(tags).To(BeEmpty())
-			})
-		})
-	})
-
-})

adapters/taglib/taglib_wrapper.cpp

@@ -1,299 +0,0 @@
-#include <stdlib.h>
-#include <string.h>
-
-#define TAGLIB_STATIC
-#include <apeproperties.h>
-#include <apetag.h>
-#include <aifffile.h>
-#include <asffile.h>
-#include <dsffile.h>
-#include <fileref.h>
-#include <flacfile.h>
-#include <id3v2tag.h>
-#include <unsynchronizedlyricsframe.h>
-#include <synchronizedlyricsframe.h>
-#include <mp4file.h>
-#include <mpegfile.h>
-#include <opusfile.h>
-#include <tpropertymap.h>
-#include <vorbisfile.h>
-#include <wavfile.h>
-#include <wavfile.h>
-#include <wavpackfile.h>
-
-#include "taglib_wrapper.h"
-
-char has_cover(const TagLib::FileRef f);
-
-static char TAGLIB_VERSION[16];
-
-char* taglib_version() {
-    snprintf((char *)TAGLIB_VERSION, 16, "%d.%d.%d", TAGLIB_MAJOR_VERSION, TAGLIB_MINOR_VERSION, TAGLIB_PATCH_VERSION);
-    return (char *)TAGLIB_VERSION;
-}
-
-int taglib_read(const FILENAME_CHAR_T *filename, unsigned long id) {
-  TagLib::FileRef f(filename, true, TagLib::AudioProperties::Fast);
-
-  if (f.isNull()) {
-    return TAGLIB_ERR_PARSE;
-  }
-
-  if (!f.audioProperties()) {
-    return TAGLIB_ERR_AUDIO_PROPS;
-  }
-
-  // Add audio properties to the tags
-  const TagLib::AudioProperties *props(f.audioProperties());
-  goPutInt(id, (char *)"__lengthinmilliseconds", props->lengthInMilliseconds());
-  goPutInt(id, (char *)"__bitrate", props->bitrate());
-  goPutInt(id, (char *)"__channels", props->channels());
-  goPutInt(id, (char *)"__samplerate", props->sampleRate());
-
-  // Extract bits per sample for supported formats
-  int bitsPerSample = 0;
-  if (const auto* apeProperties{ dynamic_cast<const TagLib::APE::Properties*>(props) })
-      bitsPerSample = apeProperties->bitsPerSample();
-  else if (const auto* asfProperties{ dynamic_cast<const TagLib::ASF::Properties*>(props) })
-      bitsPerSample = asfProperties->bitsPerSample();
-  else if (const auto* flacProperties{ dynamic_cast<const TagLib::FLAC::Properties*>(props) })
-      bitsPerSample = flacProperties->bitsPerSample();
-  else if (const auto* mp4Properties{ dynamic_cast<const TagLib::MP4::Properties*>(props) })
-      bitsPerSample = mp4Properties->bitsPerSample();
-  else if (const auto* wavePackProperties{ dynamic_cast<const TagLib::WavPack::Properties*>(props) })
-      bitsPerSample = wavePackProperties->bitsPerSample();
-  else if (const auto* aiffProperties{ dynamic_cast<const TagLib::RIFF::AIFF::Properties*>(props) })
-      bitsPerSample = aiffProperties->bitsPerSample();
-  else if (const auto* wavProperties{ dynamic_cast<const TagLib::RIFF::WAV::Properties*>(props) })
-      bitsPerSample = wavProperties->bitsPerSample();
-  else if (const auto* dsfProperties{ dynamic_cast<const TagLib::DSF::Properties*>(props) })
-      bitsPerSample = dsfProperties->bitsPerSample();
-  
-  if (bitsPerSample > 0) {
-      goPutInt(id, (char *)"__bitspersample", bitsPerSample);
-  }
-
-  // Send all properties to the Go map
-  TagLib::PropertyMap tags = f.file()->properties();
-
-  // Make sure at least the basic properties are extracted
-  TagLib::Tag *basic = f.file()->tag();
-  if (!basic->isEmpty()) {
-    if (!basic->title().isEmpty()) {
-      tags.insert("__title", basic->title());
-    }
-    if (!basic->artist().isEmpty()) {
-      tags.insert("__artist", basic->artist());
-    }
-    if (!basic->album().isEmpty()) {
-      tags.insert("__album", basic->album());
-    }
-    if (!basic->comment().isEmpty()) {
-      tags.insert("__comment", basic->comment());
-    }
-    if (!basic->genre().isEmpty()) {
-      tags.insert("__genre", basic->genre());
-    }
-    if (basic->year() > 0) {
-      tags.insert("__year", TagLib::String::number(basic->year()));
-    }
-    if (basic->track() > 0) {
-      tags.insert("__track", TagLib::String::number(basic->track()));
-    }
-  }
-
-  TagLib::ID3v2::Tag *id3Tags = NULL;
-
-  // Get some extended/non-standard ID3-only tags (ex: iTunes extended frames)
-  TagLib::MPEG::File *mp3File(dynamic_cast<TagLib::MPEG::File *>(f.file()));
-  if (mp3File != NULL) {
-    id3Tags = mp3File->ID3v2Tag();
-  }
-
-  if (id3Tags == NULL) {
-    TagLib::RIFF::WAV::File *wavFile(dynamic_cast<TagLib::RIFF::WAV::File *>(f.file()));
-    if (wavFile != NULL && wavFile->hasID3v2Tag()) {
-      id3Tags = wavFile->ID3v2Tag();
-    }
-  }
-
-  if (id3Tags == NULL) {
-    TagLib::RIFF::AIFF::File *aiffFile(dynamic_cast<TagLib::RIFF::AIFF::File *>(f.file()));
-    if (aiffFile && aiffFile->hasID3v2Tag()) {
-      id3Tags = aiffFile->tag();
-    }
-  }
-
-  // Yes, it is possible to have ID3v2 tags in FLAC. However, that can cause problems
-  // with many players, so they will not be parsed
-
-  if (id3Tags != NULL) {
-    const auto &frames = id3Tags->frameListMap();
-
-    for (const auto &kv: frames) {
-      if (kv.first == "USLT") {
-        for (const auto &tag: kv.second) {
-          TagLib::ID3v2::UnsynchronizedLyricsFrame *frame = dynamic_cast<TagLib::ID3v2::UnsynchronizedLyricsFrame *>(tag);
-          if (frame == NULL) continue;
-
-          tags.erase("LYRICS");
-
-          const auto bv = frame->language();
-          char language[4] = {'x', 'x', 'x', '\0'};
-          if (bv.size() == 3) {
-            strncpy(language, bv.data(), 3);
-          }
-
-          char *val = const_cast<char*>(frame->text().toCString(true));
-
-          goPutLyrics(id, language, val);
-        }
-      } else if (kv.first == "SYLT") {
-        for (const auto &tag: kv.second) {
-          TagLib::ID3v2::SynchronizedLyricsFrame *frame = dynamic_cast<TagLib::ID3v2::SynchronizedLyricsFrame *>(tag);
-          if (frame == NULL) continue;
-
-          const auto bv = frame->language();
-          char language[4] = {'x', 'x', 'x', '\0'};
-          if (bv.size() == 3) {
-            strncpy(language, bv.data(), 3);
-          }
-
-          const auto format = frame->timestampFormat();
-          if (format == TagLib::ID3v2::SynchronizedLyricsFrame::AbsoluteMilliseconds) {
-
-            for (const auto &line: frame->synchedText()) {
-              char *text = const_cast<char*>(line.text.toCString(true));
-              goPutLyricLine(id, language, text, line.time);
-            }
-          } else if (format == TagLib::ID3v2::SynchronizedLyricsFrame::AbsoluteMpegFrames) {
-            const int sampleRate = props->sampleRate();
-
-            if (sampleRate != 0) {
-              for (const auto &line: frame->synchedText()) {
-                const int timeInMs = (line.time * 1000) / sampleRate;
-                char *text = const_cast<char*>(line.text.toCString(true));
-                goPutLyricLine(id, language, text, timeInMs);
-              }
-            }
-          }
-        }
-      } else if (kv.first == "TIPL"){
-        if (!kv.second.isEmpty()) {
-          tags.insert(kv.first, kv.second.front()->toString());
-        }
-      }
-    }
-  }
-
-  // M4A may have some iTunes specific tags not captured by the PropertyMap interface
-  TagLib::MP4::File *m4afile(dynamic_cast<TagLib::MP4::File *>(f.file()));
-  if (m4afile != NULL) {
-    const auto itemListMap = m4afile->tag()->itemMap();
-    for (const auto item: itemListMap) {
-      char *key = const_cast<char*>(item.first.toCString(true));
-      for (const auto value: item.second.toStringList()) {
-        char *val = const_cast<char*>(value.toCString(true));
-        goPutM4AStr(id, key, val);
-      }
-    }
-  }
-
-  // WMA/ASF files may have additional tags not captured by the PropertyMap interface
-  TagLib::ASF::File *asfFile(dynamic_cast<TagLib::ASF::File *>(f.file()));
-  if (asfFile != NULL) {
-    const TagLib::ASF::Tag *asfTags{asfFile->tag()};
-    const auto itemListMap = asfTags->attributeListMap();
-    for (const auto item : itemListMap) {
-      char *key = const_cast<char*>(item.first.toCString(true));
-
-      for (auto j = item.second.begin();
-           j != item.second.end(); ++j) {
-
-        char *val = const_cast<char*>(j->toString().toCString(true));
-        goPutStr(id, key, val);
-      }
-    }
-  }
-
-  // Send all collected tags to the Go map
-  for (TagLib::PropertyMap::ConstIterator i = tags.begin(); i != tags.end();
-       ++i) {
-    char *key = const_cast<char*>(i->first.toCString(true));
-    for (TagLib::StringList::ConstIterator j = i->second.begin();
-         j != i->second.end(); ++j) {
-      char *val = const_cast<char*>((*j).toCString(true));
-      goPutStr(id, key, val);
-    }
-  }
-
-  // Cover art has to be handled separately
-  if (has_cover(f)) {
-    goPutStr(id, (char *)"has_picture", (char *)"true");
-  }
-
-  return 0;
-}
-
-// Detect if the file has cover art. Returns 1 if the file has cover art, 0 otherwise.
-char has_cover(const TagLib::FileRef f) {
-  char hasCover = 0;
-  // ----- MP3
-  if (TagLib::MPEG::File * mp3File{dynamic_cast<TagLib::MPEG::File *>(f.file())}) {
-    if (mp3File->ID3v2Tag()) {
-      const auto &frameListMap{mp3File->ID3v2Tag()->frameListMap()};
-      hasCover = !frameListMap["APIC"].isEmpty();
-    }
-  }
-  // ----- FLAC
-  else if (TagLib::FLAC::File * flacFile{dynamic_cast<TagLib::FLAC::File *>(f.file())}) {
-    hasCover = !flacFile->pictureList().isEmpty();
-  }
-  // ----- MP4
-  else if (TagLib::MP4::File * mp4File{dynamic_cast<TagLib::MP4::File *>(f.file())}) {
-    auto &coverItem{mp4File->tag()->itemMap()["covr"]};
-    TagLib::MP4::CoverArtList coverArtList{coverItem.toCoverArtList()};
-    hasCover = !coverArtList.isEmpty();
-  }
-  // ----- Ogg
-  else if (TagLib::Ogg::Vorbis::File * vorbisFile{dynamic_cast<TagLib::Ogg::Vorbis::File *>(f.file())}) {
-    hasCover = !vorbisFile->tag()->pictureList().isEmpty();
-  }
-  // ----- Opus
-  else if (TagLib::Ogg::Opus::File * opusFile{dynamic_cast<TagLib::Ogg::Opus::File *>(f.file())}) {
-    hasCover = !opusFile->tag()->pictureList().isEmpty();
-  }
-  // ----- WAV
-  else if (TagLib::RIFF::WAV::File * wavFile{ dynamic_cast<TagLib::RIFF::WAV::File*>(f.file()) }) {
-    if (wavFile->hasID3v2Tag()) {
-      const auto& frameListMap{ wavFile->ID3v2Tag()->frameListMap() };
-      hasCover = !frameListMap["APIC"].isEmpty();
-    }
-  }
-  // ----- AIFF 
-  else if (TagLib::RIFF::AIFF::File * aiffFile{ dynamic_cast<TagLib::RIFF::AIFF::File *>(f.file())}) {
-    if (aiffFile->hasID3v2Tag()) {
-      const auto& frameListMap{ aiffFile->tag()->frameListMap() };
-      hasCover = !frameListMap["APIC"].isEmpty();
-    }
-  }
-  // ----- WMA
-  else if (TagLib::ASF::File * asfFile{dynamic_cast<TagLib::ASF::File *>(f.file())}) {
-    const TagLib::ASF::Tag *tag{ asfFile->tag() };
-    hasCover = tag && tag->attributeListMap().contains("WM/Picture");
-  }
-  // ----- DSF
-  else if (TagLib::DSF::File * dsffile{ dynamic_cast<TagLib::DSF::File *>(f.file())}) {
-    const TagLib::ID3v2::Tag *tag { dsffile->tag() };
-    hasCover = tag && !tag->frameListMap()["APIC"].isEmpty();
-  }
-  // ----- WAVPAK (APE tag)
-  else if (TagLib::WavPack::File * wvFile{dynamic_cast<TagLib::WavPack::File *>(f.file())}) {
-    if (wvFile->hasAPETag()) {
-      // This is the particular string that Picard uses
-      hasCover = !wvFile->APETag()->itemListMap()["COVER ART (FRONT)"].isEmpty();
-    }
-  }
-
-  return hasCover;
-}

adapters/taglib/taglib_wrapper.go

@@ -1,157 +0,0 @@
-package taglib
-
-/*
-#cgo !windows pkg-config: --define-prefix taglib
-#cgo windows pkg-config: taglib
-#cgo illumos LDFLAGS: -lstdc++ -lsendfile
-#cgo linux darwin CXXFLAGS: -std=c++11
-#cgo darwin LDFLAGS: -L/opt/homebrew/opt/taglib/lib
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include "taglib_wrapper.h"
-*/
-import "C"
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-	"runtime/debug"
-	"strconv"
-	"strings"
-	"sync"
-	"sync/atomic"
-	"unsafe"
-
-	"github.com/navidrome/navidrome/log"
-)
-
-const iTunesKeyPrefix = "----:com.apple.itunes:"
-
-func Version() string {
-	return C.GoString(C.taglib_version())
-}
-
-func Read(filename string) (tags map[string][]string, err error) {
-	// Do not crash on failures in the C code/library
-	debug.SetPanicOnFault(true)
-	defer func() {
-		if r := recover(); r != nil {
-			log.Error("extractor: recovered from panic when reading tags", "file", filename, "error", r)
-			err = fmt.Errorf("extractor: recovered from panic: %s", r)
-		}
-	}()
-
-	fp := getFilename(filename)
-	defer C.free(unsafe.Pointer(fp))
-	id, m, release := newMap()
-	defer release()
-
-	log.Trace("extractor: reading tags", "filename", filename, "map_id", id)
-	res := C.taglib_read(fp, C.ulong(id))
-	switch res {
-	case C.TAGLIB_ERR_PARSE:
-		// Check additional case whether the file is unreadable due to permission
-		file, fileErr := os.OpenFile(filename, os.O_RDONLY, 0600)
-		defer file.Close()
-
-		if os.IsPermission(fileErr) {
-			return nil, fmt.Errorf("navidrome does not have permission: %w", fileErr)
-		} else if fileErr != nil {
-			return nil, fmt.Errorf("cannot parse file media file: %w", fileErr)
-		} else {
-			return nil, fmt.Errorf("cannot parse file media file")
-		}
-	case C.TAGLIB_ERR_AUDIO_PROPS:
-		return nil, fmt.Errorf("can't get audio properties from file")
-	}
-	if log.IsGreaterOrEqualTo(log.LevelDebug) {
-		j, _ := json.Marshal(m)
-		log.Trace("extractor: read tags", "tags", string(j), "filename", filename, "id", id)
-	} else {
-		log.Trace("extractor: read tags", "tags", m, "filename", filename, "id", id)
-	}
-
-	return m, nil
-}
-
-type tagMap map[string][]string
-
-var allMaps sync.Map
-var mapsNextID atomic.Uint32
-
-func newMap() (uint32, tagMap, func()) {
-	id := mapsNextID.Add(1)
-
-	m := tagMap{}
-	allMaps.Store(id, m)
-
-	return id, m, func() {
-		allMaps.Delete(id)
-	}
-}
-
-func doPutTag(id C.ulong, key string, val *C.char) {
-	if key == "" {
-		return
-	}
-
-	r, _ := allMaps.Load(uint32(id))
-	m := r.(tagMap)
-	k := strings.ToLower(key)
-	v := strings.TrimSpace(C.GoString(val))
-	m[k] = append(m[k], v)
-}
-
-//export goPutM4AStr
-func goPutM4AStr(id C.ulong, key *C.char, val *C.char) {
-	k := C.GoString(key)
-
-	// Special for M4A, do not catch keys that have no actual name
-	k = strings.TrimPrefix(k, iTunesKeyPrefix)
-	doPutTag(id, k, val)
-}
-
-//export goPutStr
-func goPutStr(id C.ulong, key *C.char, val *C.char) {
-	doPutTag(id, C.GoString(key), val)
-}
-
-//export goPutInt
-func goPutInt(id C.ulong, key *C.char, val C.int) {
-	valStr := strconv.Itoa(int(val))
-	vp := C.CString(valStr)
-	defer C.free(unsafe.Pointer(vp))
-	goPutStr(id, key, vp)
-}
-
-//export goPutLyrics
-func goPutLyrics(id C.ulong, lang *C.char, val *C.char) {
-	doPutTag(id, "lyrics:"+C.GoString(lang), val)
-}
-
-//export goPutLyricLine
-func goPutLyricLine(id C.ulong, lang *C.char, text *C.char, time C.int) {
-	language := C.GoString(lang)
-	line := C.GoString(text)
-	timeGo := int64(time)
-
-	ms := timeGo % 1000
-	timeGo /= 1000
-	sec := timeGo % 60
-	timeGo /= 60
-	minimum := timeGo % 60
-	formattedLine := fmt.Sprintf("[%02d:%02d.%02d]%s\n", minimum, sec, ms/10, line)
-
-	key := "lyrics:" + language
-
-	r, _ := allMaps.Load(uint32(id))
-	m := r.(tagMap)
-	k := strings.ToLower(key)
-	existing, ok := m[k]
-	if ok {
-		existing[0] += formattedLine
-	} else {
-		m[k] = []string{formattedLine}
-	}
-}

adapters/taglib/taglib_wrapper.h

@@ -1,24 +0,0 @@
-#define TAGLIB_ERR_PARSE -1
-#define TAGLIB_ERR_AUDIO_PROPS -2
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#ifdef WIN32
-#define FILENAME_CHAR_T wchar_t
-#else
-#define FILENAME_CHAR_T char
-#endif
-
-extern void goPutM4AStr(unsigned long id, char *key, char *val);
-extern void goPutStr(unsigned long id, char *key, char *val);
-extern void goPutInt(unsigned long id, char *key, int val);
-extern void goPutLyrics(unsigned long id, char *lang, char *val);
-extern void goPutLyricLine(unsigned long id, char *lang, char *text, int time);
-int taglib_read(const FILENAME_CHAR_T *filename, unsigned long id);
-char* taglib_version();
-
-#ifdef __cplusplus
-}
-#endif

cmd/pls.go

@@ -7,11 +7,19 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strconv"
+	"strings"
 
 	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/ioutils"
+	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/navidrome/navidrome/utils/str"
 	"github.com/spf13/cobra"
 )
 
@@ -20,6 +28,7 @@ var (
 	outputFile   string
 	userID       string
 	outputFormat string
+	syncFlag     bool
 )
 
 type displayPlaylist struct {
@@ -41,6 +50,15 @@ func init() {
 	listCommand.Flags().StringVarP(&userID, "user", "u", "", "username or ID")
 	listCommand.Flags().StringVarP(&outputFormat, "format", "f", "csv", "output format [supported values: csv, json]")
 	plsCmd.AddCommand(listCommand)
+
+	exportCommand.Flags().StringVarP(&playlistID, "playlist", "p", "", "playlist name or ID")
+	exportCommand.Flags().StringVarP(&outputFile, "output", "o", "", "output directory")
+	exportCommand.Flags().StringVarP(&userID, "user", "u", "", "username or ID")
+	plsCmd.AddCommand(exportCommand)
+
+	importCommand.Flags().StringVarP(&userID, "user", "u", "", "owner username or ID (default: first admin)")
+	importCommand.Flags().BoolVar(&syncFlag, "sync", false, "mark imported playlists as synced")
+	plsCmd.AddCommand(importCommand)
 }
 
 var (
@@ -60,72 +78,165 @@ var (
 			runList(cmd.Context())
 		},
 	}
+
+	exportCommand = &cobra.Command{
+		Use:   "export",
+		Short: "Export playlists to M3U files",
+		Long:  "Export one or more Navidrome playlists to M3U files",
+		Run: func(cmd *cobra.Command, args []string) {
+			runExport(cmd.Context())
+		},
+	}
+
+	importCommand = &cobra.Command{
+		Use:   "import [files...]",
+		Short: "Import M3U playlists",
+		Long:  "Import one or more M3U files as Navidrome playlists",
+		Args:  cobra.MinimumNArgs(1),
+		Run: func(cmd *cobra.Command, args []string) {
+			runImport(cmd.Context(), args)
+		},
+	}
 )
 
-func runExporter(ctx context.Context) {
-	ds, ctx := getAdminContext(ctx)
-	playlist, err := ds.Playlist(ctx).GetWithTracks(playlistID, true, false)
+func fetchPlaylists(ctx context.Context, ds model.DataStore, sort string) model.Playlists {
+	options := model.QueryOptions{Sort: sort}
+	if userID != "" {
+		user, err := getUser(ctx, userID, ds)
+		if err != nil {
+			log.Fatal(ctx, "Error retrieving user", "username or id", userID)
+		}
+		options.Filters = squirrel.Eq{"owner_id": user.ID}
+	}
+	pls, err := ds.Playlist(ctx).GetAll(options)
+	if err != nil {
+		log.Fatal(ctx, "Failed to retrieve playlists", err)
+	}
+	return pls
+}
+
+func findPlaylist(ctx context.Context, ds model.DataStore, nameOrID string) *model.Playlist {
+	playlist, err := ds.Playlist(ctx).GetWithTracks(nameOrID, true, false)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
-		log.Fatal("Error retrieving playlist", "name", playlistID, err)
+		log.Fatal("Error retrieving playlist", "name", nameOrID, err)
 	}
 	if errors.Is(err, model.ErrNotFound) {
-		playlists, err := ds.Playlist(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"playlist.name": playlistID}})
+		playlists, err := ds.Playlist(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"playlist.name": nameOrID}})
 		if err != nil {
-			log.Fatal("Error retrieving playlist", "name", playlistID, err)
+			log.Fatal("Error retrieving playlist", "name", nameOrID, err)
 		}
 		if len(playlists) > 0 {
 			playlist, err = ds.Playlist(ctx).GetWithTracks(playlists[0].ID, true, false)
 			if err != nil {
-				log.Fatal("Error retrieving playlist", "name", playlistID, err)
+				log.Fatal("Error retrieving playlist", "name", nameOrID, err)
 			}
 		}
 	}
 	if playlist == nil {
-		log.Fatal("Playlist not found", "name", playlistID)
+		log.Fatal("Playlist not found", "name", nameOrID)
 	}
+	return playlist
+}
+
+func runExporter(ctx context.Context) {
+	ds, ctx := getAdminContext(ctx)
+	playlist := findPlaylist(ctx, ds, playlistID)
 	pls := playlist.ToM3U8()
 	if outputFile == "-" || outputFile == "" {
 		println(pls)
 		return
 	}
-
-	err = os.WriteFile(outputFile, []byte(pls), 0600)
+	err := os.WriteFile(outputFile, []byte(pls), 0600)
 	if err != nil {
 		log.Fatal("Error writing to the output file", "file", outputFile, err)
 	}
 }
 
+func runExport(ctx context.Context) {
+	ds, ctx := getAdminContext(ctx)
+
+	if playlistID != "" && outputFile == "" {
+		playlist := findPlaylist(ctx, ds, playlistID)
+		println(playlist.ToM3U8())
+		return
+	}
+
+	if outputFile == "" {
+		log.Fatal("Output directory (-o) is required for bulk export or when filtering by user")
+	}
+
+	info, err := os.Stat(outputFile)
+	if err != nil || !info.IsDir() {
+		log.Fatal("Output path must be an existing directory", "path", outputFile)
+	}
+
+	if playlistID != "" {
+		pls := findPlaylist(ctx, ds, playlistID)
+		filename := str.SanitizeFilename(pls.Name) + ".m3u"
+		path := filepath.Join(outputFile, filename)
+		err := os.WriteFile(path, []byte(pls.ToM3U8()), 0600)
+		if err != nil {
+			log.Fatal("Error writing playlist", "file", path, err)
+		}
+		fmt.Printf("Exported \"%s\" to %s\n", pls.Name, path)
+		return
+	}
+
+	allPls := fetchPlaylists(ctx, ds, "name")
+
+	nameCounts := make(map[string]int)
+	for _, pls := range allPls {
+		nameCounts[str.SanitizeFilename(pls.Name)]++
+	}
+
+	exported := 0
+	for _, pls := range allPls {
+		plsWithTracks, err := ds.Playlist(ctx).GetWithTracks(pls.ID, true, false)
+		if err != nil {
+			log.Error("Error loading playlist tracks", "playlist", pls.Name, err)
+			continue
+		}
+
+		sanitized := str.SanitizeFilename(pls.Name)
+		filename := sanitized + ".m3u"
+		if nameCounts[sanitized] > 1 {
+			shortID := pls.ID
+			if len(shortID) > 6 {
+				shortID = shortID[:6]
+			}
+			filename = sanitized + "_" + shortID + ".m3u"
+		}
+
+		path := filepath.Join(outputFile, filename)
+		err = os.WriteFile(path, []byte(plsWithTracks.ToM3U8()), 0600)
+		if err != nil {
+			log.Error("Error writing playlist", "file", path, err)
+			continue
+		}
+		fmt.Printf("Exported \"%s\" to %s\n", pls.Name, path)
+		exported++
+	}
+	fmt.Printf("\nExported %d playlists to %s\n", exported, outputFile)
+}
+
 func runList(ctx context.Context) {
 	if outputFormat != "csv" && outputFormat != "json" {
 		log.Fatal("Invalid output format. Must be one of csv, json", "format", outputFormat)
 	}
 
 	ds, ctx := getAdminContext(ctx)
-	options := model.QueryOptions{Sort: "owner_name"}
-
-	if userID != "" {
-		user, err := getUser(ctx, userID, ds)
-		if err != nil {
-			log.Fatal(ctx, "Error retrieving user", "username or id", userID)
-		}
-		options.Filters = squirrel.Eq{"owner_id": user.ID}
-	}
-
-	playlists, err := ds.Playlist(ctx).GetAll(options)
-	if err != nil {
-		log.Fatal(ctx, "Failed to retrieve playlists", err)
-	}
+	allPls := fetchPlaylists(ctx, ds, "owner_name")
 
 	if outputFormat == "csv" {
 		w := csv.NewWriter(os.Stdout)
 		_ = w.Write([]string{"playlist id", "playlist name", "owner id", "owner name", "public"})
-		for _, playlist := range playlists {
+		for _, playlist := range allPls {
 			_ = w.Write([]string{playlist.ID, playlist.Name, playlist.OwnerID, playlist.OwnerName, strconv.FormatBool(playlist.Public)})
 		}
 		w.Flush()
 	} else {
-		display := make(displayPlaylists, len(playlists))
-		for idx, playlist := range playlists {
+		display := make(displayPlaylists, len(allPls))
+		for idx, playlist := range allPls {
 			display[idx].Id = playlist.ID
 			display[idx].Name = playlist.Name
 			display[idx].OwnerId = playlist.OwnerID
@@ -137,3 +248,62 @@ func runList(ctx context.Context) {
 		fmt.Printf("%s\n", j)
 	}
 }
+
+func runImport(ctx context.Context, files []string) {
+	ds, ctx := getAdminContext(ctx)
+
+	if userID != "" {
+		user, err := getUser(ctx, userID, ds)
+		if err != nil {
+			log.Fatal(ctx, "Error retrieving user", "username or id", userID)
+		}
+		ctx = request.WithUser(ctx, *user)
+	}
+
+	pls := playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+	for _, file := range files {
+		absPath, err := filepath.Abs(file)
+		if err != nil {
+			log.Error("Error resolving path", "file", file, err)
+			fmt.Fprintf(os.Stderr, "Error: could not resolve path %s: %v\n", file, err)
+			continue
+		}
+
+		totalLines := countM3UTrackLines(absPath)
+
+		imported, err := pls.ImportFile(ctx, absPath, syncFlag)
+		if err != nil {
+			log.Error("Error importing playlist", "file", absPath, err)
+			fmt.Fprintf(os.Stderr, "Error importing %s: %v\n", file, err)
+			continue
+		}
+
+		matched := len(imported.Tracks)
+		if totalLines > 0 {
+			notFound := totalLines - matched
+			fmt.Printf("Imported \"%s\" — %d/%d tracks matched (%d not found)\n", imported.Name, matched, totalLines, notFound)
+		} else {
+			fmt.Printf("Imported \"%s\" — %d tracks\n", imported.Name, matched)
+		}
+	}
+}
+
+func countM3UTrackLines(path string) int {
+	file, err := os.Open(path)
+	if err != nil {
+		return 0
+	}
+	defer file.Close()
+
+	count := 0
+	reader := ioutils.UTF8Reader(file)
+	for line := range slice.LinesFrom(reader) {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		count++
+	}
+	return count
+}

cmd/root.go

@@ -27,7 +27,6 @@ import (
 	_ "github.com/navidrome/navidrome/adapters/gotaglib"
 	_ "github.com/navidrome/navidrome/adapters/lastfm"
 	_ "github.com/navidrome/navidrome/adapters/listenbrainz"
-	_ "github.com/navidrome/navidrome/adapters/taglib"
 )
 
 var (

cmd/wire_gen.go

@@ -17,10 +17,12 @@ import (
 	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/core/lyrics"
+	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playback"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/core/scrobbler"
+	"github.com/navidrome/navidrome/core/sonic"
 	"github.com/navidrome/navidrome/core/stream"
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/model"
@@ -39,7 +41,6 @@ import (
 	_ "github.com/navidrome/navidrome/adapters/gotaglib"
 	_ "github.com/navidrome/navidrome/adapters/lastfm"
 	_ "github.com/navidrome/navidrome/adapters/listenbrainz"
-	_ "github.com/navidrome/navidrome/adapters/taglib"
 )
 
 // Injectors from wire_injectors.go:
@@ -72,7 +73,8 @@ func CreateNativeAPIRouter(ctx context.Context) *nativeapi.Router {
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
 	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	agentsAgents := agents.GetAgents(dataStore, manager)
-	provider := external.NewProvider(dataStore, agentsAgents)
+	matcherMatcher := matcher.New(dataStore)
+	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
 	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
 	cacheWarmer := artwork.NewCacheWarmer(artworkArtwork, fileCache)
 	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
@@ -93,7 +95,8 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
 	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	agentsAgents := agents.GetAgents(dataStore, manager)
-	provider := external.NewProvider(dataStore, agentsAgents)
+	matcherMatcher := matcher.New(dataStore)
+	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
 	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
 	transcodingCache := stream.GetTranscodingCache()
 	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
@@ -108,7 +111,8 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	playbackServer := playback.GetInstance(dataStore)
 	lyricsLyrics := lyrics.NewLyrics(manager)
 	transcodeDecider := stream.NewTranscodeDecider(dataStore, fFmpeg)
-	router := subsonic.New(dataStore, artworkArtwork, mediaStreamer, archiver, players, provider, modelScanner, broker, playlistsPlaylists, playTracker, share, playbackServer, metricsMetrics, lyricsLyrics, transcodeDecider)
+	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)
 	return router
 }
 
@@ -121,7 +125,8 @@ func CreatePublicRouter() *public.Router {
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
 	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	agentsAgents := agents.GetAgents(dataStore, manager)
-	provider := external.NewProvider(dataStore, agentsAgents)
+	matcherMatcher := matcher.New(dataStore)
+	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
 	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
 	transcodingCache := stream.GetTranscodingCache()
 	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
@@ -168,7 +173,8 @@ func CreateScanner(ctx context.Context) model.Scanner {
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
 	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	agentsAgents := agents.GetAgents(dataStore, manager)
-	provider := external.NewProvider(dataStore, agentsAgents)
+	matcherMatcher := matcher.New(dataStore)
+	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
 	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
 	cacheWarmer := artwork.NewCacheWarmer(artworkArtwork, fileCache)
 	imageUploadService := core.NewImageUploadService()
@@ -186,7 +192,8 @@ func CreateScanWatcher(ctx context.Context) scanner.Watcher {
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
 	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	agentsAgents := agents.GetAgents(dataStore, manager)
-	provider := external.NewProvider(dataStore, agentsAgents)
+	matcherMatcher := matcher.New(dataStore)
+	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
 	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
 	cacheWarmer := artwork.NewCacheWarmer(artworkArtwork, fileCache)
 	imageUploadService := core.NewImageUploadService()
@@ -214,7 +221,7 @@ func getPluginManager() *plugins.Manager {
 
 // wire_injectors.go:
 
-var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, nativeapi.New, public.New, persistence.New, lastfm.NewRouter, listenbrainz.NewRouter, events.GetBroker, scanner.New, scanner.GetWatcher, metrics.GetPrometheusInstance, db.Db, plugins.GetManager, wire.Bind(new(agents.PluginLoader), new(*plugins.Manager)), wire.Bind(new(scrobbler.PluginLoader), new(*plugins.Manager)), wire.Bind(new(lyrics.PluginLoader), new(*plugins.Manager)), wire.Bind(new(nativeapi.PluginManager), new(*plugins.Manager)), wire.Bind(new(core.PluginUnloader), new(*plugins.Manager)), wire.Bind(new(plugins.PluginMetricsRecorder), new(metrics.Metrics)), wire.Bind(new(core.Watcher), new(scanner.Watcher)))
+var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, nativeapi.New, public.New, persistence.New, lastfm.NewRouter, listenbrainz.NewRouter, events.GetBroker, scanner.New, scanner.GetWatcher, metrics.GetPrometheusInstance, db.Db, plugins.GetManager, sonic.New, wire.Bind(new(agents.PluginLoader), new(*plugins.Manager)), wire.Bind(new(scrobbler.PluginLoader), new(*plugins.Manager)), wire.Bind(new(lyrics.PluginLoader), new(*plugins.Manager)), wire.Bind(new(sonic.PluginLoader), new(*plugins.Manager)), wire.Bind(new(nativeapi.PluginManager), new(*plugins.Manager)), wire.Bind(new(core.PluginUnloader), new(*plugins.Manager)), wire.Bind(new(plugins.PluginMetricsRecorder), new(metrics.Metrics)), wire.Bind(new(core.Watcher), new(scanner.Watcher)))
 
 func GetPluginManager(ctx context.Context) *plugins.Manager {
 	manager := getPluginManager()

cmd/wire_injectors.go

@@ -15,6 +15,7 @@ import (
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playback"
 	"github.com/navidrome/navidrome/core/scrobbler"
+	"github.com/navidrome/navidrome/core/sonic"
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/persistence"
@@ -43,9 +44,11 @@ var allProviders = wire.NewSet(
 	metrics.GetPrometheusInstance,
 	db.Db,
 	plugins.GetManager,
+	sonic.New,
 	wire.Bind(new(agents.PluginLoader), new(*plugins.Manager)),
 	wire.Bind(new(scrobbler.PluginLoader), new(*plugins.Manager)),
 	wire.Bind(new(lyrics.PluginLoader), new(*plugins.Manager)),
+	wire.Bind(new(sonic.PluginLoader), new(*plugins.Manager)),
 	wire.Bind(new(nativeapi.PluginManager), new(*plugins.Manager)),
 	wire.Bind(new(core.PluginUnloader), new(*plugins.Manager)),
 	wire.Bind(new(plugins.PluginMetricsRecorder), new(metrics.Metrics)),

conf/configuration.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/bmatcuk/doublestar/v4"
+	"github.com/dustin/go-humanize"
 	"github.com/go-viper/encoding/ini"
 	"github.com/kr/pretty"
 	"github.com/navidrome/navidrome/consts"
@@ -26,6 +27,7 @@ type configOptions struct {
 	Address                         string
 	Port                            int
 	UnixSocketPerm                  string
+	EnforceNonRootUser              bool
 	MusicFolder                     string
 	DataFolder                      string
 	CacheFolder                     string
@@ -59,8 +61,8 @@ type configOptions struct {
 	SmartPlaylistRefreshDelay       time.Duration
 	AutoTranscodeDownload           bool
 	DefaultDownsamplingFormat       string
-	Search                          searchOptions `json:",omitzero"`
-	SimilarSongsMatchThreshold      int
+	Search                          searchOptions  `json:",omitzero"`
+	Matcher                         matcherOptions `json:",omitzero"`
 	RecentlyAddedByModTime          bool
 	PreferSortTags                  bool
 	IgnoredArticles                 string
@@ -70,6 +72,7 @@ type configOptions struct {
 	MPVCmdTemplate                  string
 	CoverArtPriority                string
 	CoverArtQuality                 int
+	EnableWebPEncoding              bool
 	ArtistArtPriority               string
 	ArtistImageFolder               string
 	DiscArtPriority                 string
@@ -79,6 +82,7 @@ type configOptions struct {
 	EnableStarRating                bool
 	EnableUserEditing               bool
 	EnableArtworkUpload             bool
+	MaxImageUploadSize              string
 	EnableSharing                   bool
 	ShareURL                        string
 	DefaultShareExpiration          time.Duration
@@ -87,9 +91,11 @@ type configOptions struct {
 	DefaultLanguage                 string
 	DefaultUIVolume                 int
 	UISearchDebounceMs              int
+	UICoverArtSize                  int
 	EnableReplayGain                bool
 	EnableCoverAnimation            bool
 	EnableNowPlaying                bool
+	UIPlaybackReportInterval        time.Duration
 	GATrackingID                    string
 	EnableLogRedacting              bool
 	AuthRequestLimit                int
@@ -141,7 +147,6 @@ type configOptions struct {
 	DevOptimizeDB                     bool
 	DevPreserveUnicodeInExternalCalls bool
 	DevEnableMediaFileProbe           bool
-	DevJpegCoverArt                   bool
 }
 
 type scannerOptions struct {
@@ -258,6 +263,11 @@ type searchOptions struct {
 	FullString bool
 }
 
+type matcherOptions struct {
+	PreferStarred  bool
+	FuzzyThreshold int
+}
+
 // logFatal prints a fatal error message to stderr and exits.
 // Overridden in tests to allow testing fatal paths.
 var logFatal = func(args ...any) {
@@ -265,6 +275,12 @@ var logFatal = func(args ...any) {
 	os.Exit(1)
 }
 
+var getEUID = os.Geteuid
+
+var currentGOOS = func() string {
+	return runtime.GOOS
+}
+
 var (
 	Server = &configOptions{}
 	hooks  []func()
@@ -288,12 +304,18 @@ func Load(noConfigDump bool) {
 	mapDeprecatedOption("ReverseProxyUserHeader", "ExtAuth.UserHeader")
 	mapDeprecatedOption("HTTPSecurityHeaders.CustomFrameOptionsValue", "HTTPHeaders.FrameOptions")
 	mapDeprecatedOption("CoverJpegQuality", "CoverArtQuality")
+	mapDeprecatedOption("SimilarSongsMatchThreshold", "Matcher.FuzzyThreshold")
 
 	err := viper.Unmarshal(&Server)
 	if err != nil {
 		logFatal("Error parsing config:", err)
 	}
 
+	// Validate non-root user early, before any filesystem operations
+	if err := validateEnforceNonRootUser(); err != nil {
+		logFatal(err)
+	}
+
 	err = os.MkdirAll(Server.DataFolder, os.ModePerm)
 	if err != nil {
 		logFatal("Error creating data path:", err)
@@ -359,10 +381,11 @@ func Load(noConfigDump bool) {
 		validateBackupSchedule,
 		validatePlaylistsPath,
 		validatePurgeMissingOption,
+		validateMaxImageUploadSize,
 		validateURL("ExtAuth.LogoutURL", Server.ExtAuth.LogoutURL),
 	)
 	if err != nil {
-		os.Exit(1)
+		logFatal(err)
 	}
 
 	Server.Search.Backend = normalizeSearchBackend(Server.Search.Backend)
@@ -420,10 +443,18 @@ func Load(noConfigDump bool) {
 	logDeprecatedOptions("ReverseProxyUserHeader", "ExtAuth.UserHeader")
 	logDeprecatedOptions("HTTPSecurityHeaders.CustomFrameOptionsValue", "HTTPHeaders.FrameOptions")
 	logDeprecatedOptions("CoverJpegQuality", "CoverArtQuality")
+	logDeprecatedOptions("SimilarSongsMatchThreshold", "Matcher.FuzzyThreshold")
 
 	// Removed options
 	logRemovedOptions("Spotify.ID", "Spotify.Secret")
 
+	// Validate other options
+	if Server.UICoverArtSize < 200 || Server.UICoverArtSize > 1200 {
+		newValue := max(200, min(1200, Server.UICoverArtSize))
+		log.Warn("UICoverArtSize must be between 200 and 1200, clamping", "value", Server.UICoverArtSize, "newValue", newValue)
+		Server.UICoverArtSize = newValue
+	}
+
 	// Call init hooks
 	for _, hook := range hooks {
 		hook()
@@ -541,8 +572,7 @@ func validatePlaylistsPath() error {
 	for path := range strings.SplitSeq(Server.PlaylistsPath, string(filepath.ListSeparator)) {
 		_, err := doublestar.Match(path, "")
 		if err != nil {
-			log.Error("Invalid PlaylistsPath", "path", path, err)
-			return err
+			return fmt.Errorf("invalid PlaylistsPath %q: %w", path, err)
 		}
 	}
 	return nil
@@ -569,13 +599,31 @@ func validatePurgeMissingOption() error {
 	valid := slices.Contains(allowedValues, Server.Scanner.PurgeMissing)
 	if !valid {
 		err := fmt.Errorf("invalid Scanner.PurgeMissing value: '%s'. Must be one of: %v", Server.Scanner.PurgeMissing, allowedValues)
-		log.Error(err.Error())
 		Server.Scanner.PurgeMissing = consts.PurgeMissingNever
 		return err
 	}
 	return nil
 }
 
+func validateMaxImageUploadSize() error {
+	if _, err := humanize.ParseBytes(Server.MaxImageUploadSize); err != nil {
+		return fmt.Errorf("invalid MaxImageUploadSize %q: use values like '10MB', '1GB', or raw bytes like '10485760': %w", Server.MaxImageUploadSize, err)
+	}
+	return nil
+}
+
+func validateEnforceNonRootUser() error {
+	if !Server.EnforceNonRootUser || currentGOOS() == "windows" {
+		return nil
+	}
+
+	if getEUID() == 0 {
+		return fmt.Errorf("EnforceNonRootUser is enabled but Navidrome is running as root")
+	}
+
+	return nil
+}
+
 func validateScanSchedule() error {
 	if Server.Scanner.Schedule == "0" || Server.Scanner.Schedule == "" {
 		Server.Scanner.Schedule = ""
@@ -599,9 +647,9 @@ func validateBackupSchedule() error {
 func validateSchedule(schedule, field string) (string, error) {
 	_, err := scheduler.ParseCrontab(schedule)
 	if err != nil {
-		log.Error(fmt.Sprintf("Invalid %s. Please read format spec at https://pkg.go.dev/github.com/robfig/cron#hdr-CRON_Expression_Format", field), "schedule", schedule, err)
+		return schedule, fmt.Errorf("invalid %s %q (see https://pkg.go.dev/github.com/robfig/cron#hdr-CRON_Expression_Format): %w", field, schedule, err)
 	}
-	return schedule, err
+	return schedule, nil
 }
 
 // validateURL checks if the provided URL is valid and has either http or https scheme.
@@ -613,19 +661,13 @@ func validateURL(optionName, optionURL string) func() error {
 		}
 		u, err := url.Parse(optionURL)
 		if err != nil {
-			log.Error(fmt.Sprintf("Invalid %s: it could not be parsed", optionName), "url", optionURL, "err", err)
-			return err
+			return fmt.Errorf("invalid %s %q: %w", optionName, optionURL, err)
 		}
 		if u.Scheme != "http" && u.Scheme != "https" {
-			err := fmt.Errorf("invalid scheme for %s: '%s'. Only 'http' and 'https' are allowed", optionName, u.Scheme)
-			log.Error(err.Error())
-			return err
+			return fmt.Errorf("invalid scheme for %s: '%s'. Only 'http' and 'https' are allowed", optionName, u.Scheme)
 		}
-		// Require an absolute URL with a non-empty host and no opaque component.
 		if u.Host == "" || u.Opaque != "" {
-			err := fmt.Errorf("invalid %s: '%s'. A full http(s) URL with a non-empty host is required", optionName, optionURL)
-			log.Error(err.Error())
-			return err
+			return fmt.Errorf("invalid %s: '%s'. A full http(s) URL with a non-empty host is required", optionName, optionURL)
 		}
 		return nil
 	}
@@ -681,6 +723,7 @@ func setViperDefaults() {
 	viper.SetDefault("address", "0.0.0.0")
 	viper.SetDefault("port", 4533)
 	viper.SetDefault("unixsocketperm", "0660")
+	viper.SetDefault("enforcenonrootuser", false)
 	viper.SetDefault("sessiontimeout", consts.DefaultSessionTimeout)
 	viper.SetDefault("baseurl", "")
 	viper.SetDefault("tlscert", "")
@@ -706,7 +749,8 @@ func setViperDefaults() {
 	viper.SetDefault("defaultdownsamplingformat", consts.DefaultDownsamplingFormat)
 	viper.SetDefault("search.fullstring", false)
 	viper.SetDefault("search.backend", "fts")
-	viper.SetDefault("similarsongsmatchthreshold", 85)
+	viper.SetDefault("matcher.preferstarred", true)
+	viper.SetDefault("matcher.fuzzythreshold", 85)
 	viper.SetDefault("recentlyaddedbymodtime", false)
 	viper.SetDefault("prefersorttags", false)
 	viper.SetDefault("ignoredarticles", "The El La Los Las Le Les Os As O A")
@@ -716,6 +760,7 @@ func setViperDefaults() {
 	viper.SetDefault("mpvcmdtemplate", "mpv --audio-device=%d --no-audio-display %f --input-ipc-server=%s")
 	viper.SetDefault("coverartpriority", "cover.*, folder.*, front.*, embedded, external")
 	viper.SetDefault("coverartquality", 75)
+	viper.SetDefault("enablewebpencoding", false)
 	viper.SetDefault("artistartpriority", "artist.*, album/artist.*, external")
 	viper.SetDefault("artistimagefolder", "")
 	viper.SetDefault("discartpriority", "disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded")
@@ -728,10 +773,13 @@ func setViperDefaults() {
 	viper.SetDefault("defaultlanguage", "")
 	viper.SetDefault("defaultuivolume", consts.DefaultUIVolume)
 	viper.SetDefault("uisearchdebouncems", consts.DefaultUISearchDebounceMs)
+	viper.SetDefault("uicoverartsize", consts.DefaultUICoverArtSize)
 	viper.SetDefault("enablereplaygain", true)
 	viper.SetDefault("enablecoveranimation", true)
 	viper.SetDefault("enablenowplaying", true)
+	viper.SetDefault("uiplaybackreportinterval", consts.DefaultUIPlaybackReportInterval)
 	viper.SetDefault("enableartworkupload", true)
+	viper.SetDefault("maximageuploadsize", consts.DefaultMaxImageUploadSize)
 	viper.SetDefault("enablesharing", false)
 	viper.SetDefault("shareurl", "")
 	viper.SetDefault("defaultshareexpiration", 8760*time.Hour)
@@ -810,7 +858,7 @@ func setViperDefaults() {
 	viper.SetDefault("devuishowconfig", true)
 	viper.SetDefault("devneweventstream", true)
 	viper.SetDefault("devoffsetoptimize", 50000)
-	viper.SetDefault("devartworkmaxrequests", max(4, runtime.NumCPU()))
+	viper.SetDefault("devartworkmaxrequests", max(2, runtime.NumCPU()/2))
 	viper.SetDefault("devartworkthrottlebackloglimit", consts.RequestThrottleBacklogLimit)
 	viper.SetDefault("devartworkthrottlebacklogtimeout", consts.RequestThrottleBacklogTimeout)
 	viper.SetDefault("devartistinfotimetolive", consts.ArtistInfoTimeToLive)
@@ -826,7 +874,6 @@ func setViperDefaults() {
 	viper.SetDefault("devoptimizedb", true)
 	viper.SetDefault("devpreserveunicodeinexternalcalls", false)
 	viper.SetDefault("devenablemediafileprobe", true)
-	viper.SetDefault("devjpegcoverart", false)
 }
 
 func init() {

conf/configuration_test.go

@@ -219,6 +219,80 @@ var _ = Describe("Configuration", func() {
 
 	})
 
+	Describe("ValidateMaxImageUploadSize", func() {
+		BeforeEach(func() {
+			viper.Reset()
+			conf.SetViperDefaults()
+			viper.SetDefault("datafolder", GinkgoT().TempDir())
+			viper.SetDefault("loglevel", "error")
+			conf.ResetConf()
+		})
+
+		DescribeTable("accepts valid size values",
+			func(input string) {
+				conf.Server.MaxImageUploadSize = input
+				Expect(conf.ValidateMaxImageUploadSize()).To(Succeed())
+			},
+			Entry("megabytes", "10MB"),
+			Entry("gigabytes", "1GB"),
+			Entry("raw bytes", "10485760"),
+			Entry("mebibytes", "10MiB"),
+			Entry("lower case", "50mb"),
+		)
+
+		DescribeTable("rejects invalid size values",
+			func(input string) {
+				conf.Server.MaxImageUploadSize = input
+				Expect(conf.ValidateMaxImageUploadSize()).To(MatchError(ContainSubstring("invalid MaxImageUploadSize")))
+			},
+			Entry("garbage string", "not-a-size"),
+			Entry("negative-looking", "-10MB"),
+		)
+	})
+
+	Describe("EnforceNonRootUser", func() {
+		It("defaults to false", func() {
+			conf.Load(true)
+
+			Expect(conf.Server.EnforceNonRootUser).To(BeFalse())
+		})
+
+		It("allows startup for non-root users when enabled", func() {
+			DeferCleanup(conf.SetRuntimeInfoForTest("linux", 1000))
+			viper.Set("enforcenonrootuser", true)
+
+			conf.Load(true)
+
+			Expect(conf.Server.EnforceNonRootUser).To(BeTrue())
+		})
+
+		It("exits when enabled and running as root without having created a data folder", func() {
+			// Create a path that doesn't exist yet
+			tempBase := GinkgoT().TempDir()
+			nonExistentDataFolder := filepath.Join(tempBase, "nonexistent", "data")
+			DeferCleanup(conf.SetRuntimeInfoForTest("linux", 0))
+			viper.Set("enforcenonrootuser", true)
+			viper.Set("datafolder", nonExistentDataFolder)
+
+			// Attempt to load config as root user - should fail before creating directories
+			Expect(func() {
+				conf.Load(true)
+			}).To(PanicWith(ContainSubstring("EnforceNonRootUser is enabled but Navidrome is running as root")))
+
+			// Verify that the data folder was NOT created
+			Expect(nonExistentDataFolder).ToNot(BeAnExistingFile())
+		})
+
+		It("is a no-op on non-unix platforms", func() {
+			DeferCleanup(conf.SetRuntimeInfoForTest("windows", 0))
+			viper.Set("enforcenonrootuser", true)
+
+			conf.Load(true)
+
+			Expect(conf.Server.EnforceNonRootUser).To(BeTrue())
+		})
+	})
+
 	DescribeTable("should load configuration from",
 		func(format string) {
 			filename := filepath.Join("testdata", "cfg."+format)

conf/export_test.go

@@ -14,6 +14,19 @@ var NormalizeSearchBackend = normalizeSearchBackend
 
 var ToPascalCase = toPascalCase
 
+var ValidateMaxImageUploadSize = validateMaxImageUploadSize
+
+func SetRuntimeInfoForTest(goos string, euid int) func() {
+	oldGOOS := currentGOOS
+	oldEUID := getEUID
+	currentGOOS = func() string { return goos }
+	getEUID = func() int { return euid }
+	return func() {
+		currentGOOS = oldGOOS
+		getEUID = oldEUID
+	}
+}
+
 func SetLogFatal(f func(...any)) func() {
 	old := logFatal
 	logFatal = f

consts/consts.go

@@ -67,11 +67,12 @@ const (
 	ScanIgnoreFile = ".ndignore"
 	ArtworkFolder  = "artwork"
 
-	PlaceholderArtistArt      = "artist-placeholder.webp"
-	PlaceholderAlbumArt       = "album-placeholder.webp"
-	PlaceholderAvatar         = "logo-192x192.png"
-	DefaultUIVolume           = 100
-	DefaultUISearchDebounceMs = 200
+	PlaceholderArtistArt            = "artist-placeholder.webp"
+	PlaceholderAlbumArt             = "album-placeholder.webp"
+	PlaceholderAvatar               = "logo-192x192.png"
+	DefaultUIVolume                 = 100
+	DefaultUISearchDebounceMs       = 200
+	DefaultUIPlaybackReportInterval = time.Minute
 
 	DefaultHttpClientTimeOut = 10 * time.Second
 
@@ -85,11 +86,10 @@ const (
 )
 
 const (
-	UICoverArtSize = 600
+	DefaultUICoverArtSize     = 300
+	DefaultMaxImageUploadSize = "10MB"
 )
 
-var CacheWarmerImageSizes = []int{UICoverArtSize}
-
 // Prometheus options
 const (
 	PrometheusDefaultPath = "/metrics"

context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/navidrome/navidrome",
+  "public_key": "pk_WqzhKScNKWQ84J4n0oG0J"
+}

core/archiver.go

@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/navidrome/navidrome/utils/str"
 )
 
 type Archiver interface {
@@ -87,7 +88,7 @@ func (a *archiver) albumFilename(mf model.MediaFile, format string, isMultiDisc
 	if isMultiDisc {
 		file = fmt.Sprintf("Disc %02d/%s", mf.DiscNumber, file)
 	}
-	return fmt.Sprintf("%s/%s", sanitizeName(mf.Album), file)
+	return fmt.Sprintf("%s/%s", str.SanitizeFilename(mf.Album), file)
 }
 
 func (a *archiver) ZipShare(ctx context.Context, id string, out io.Writer) error {
@@ -126,7 +127,7 @@ func (a *archiver) zipMediaFiles(ctx context.Context, id, name string, format st
 
 	// Add M3U file if requested
 	if addM3U && len(zippedMfs) > 0 {
-		plsName := sanitizeName(name)
+		plsName := str.SanitizeFilename(name)
 		w, err := z.CreateHeader(&zip.FileHeader{
 			Name:     plsName + ".m3u",
 			Modified: mfs[0].UpdatedAt,
@@ -156,11 +157,7 @@ func (a *archiver) playlistFilename(mf model.MediaFile, format string, idx int)
 	if format != "" && format != "raw" {
 		ext = format
 	}
-	return fmt.Sprintf("%02d - %s - %s.%s", idx+1, sanitizeName(mf.Artist), sanitizeName(mf.Title), ext)
-}
-
-func sanitizeName(target string) string {
-	return strings.ReplaceAll(target, "/", "_")
+	return fmt.Sprintf("%02d - %s - %s.%s", idx+1, str.SanitizeFilename(mf.Artist), str.SanitizeFilename(mf.Title), ext)
 }
 
 func (a *archiver) addFileToZip(ctx context.Context, z *zip.Writer, mf model.MediaFile, format string, bitrate int, filename string) error {

core/artwork/artwork_internal_test.go

@@ -7,12 +7,11 @@ import (
 	"image/jpeg"
 	"image/png"
 	"io"
-
 	"os"
 	"path/filepath"
+	"time"
 
 	_ "github.com/gen2brain/webp"
-
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/log"
@@ -38,10 +37,15 @@ var _ = Describe("Artwork", func() {
 		conf.Server.CoverArtPriority = "folder.*, cover.*, embedded , front.*"
 
 		folderRepo = &fakeFolderRepo{}
+		libRepo := &tests.MockLibraryRepo{}
+		repoRoot, _ := os.Getwd()
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
 		ds = &tests.MockDataStore{
 			MockedTranscoding: &tests.MockTranscodingRepo{},
 			MockedFolder:      folderRepo,
+			MockedLibrary:     libRepo,
 		}
+		// Paths use forward slashes because the scanner stores fs.FS-relative paths in the DB.
 		alOnlyEmbed = model.Album{ID: "222", Name: "Only embed", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}}
 		alEmbedNotFound = model.Album{ID: "333", Name: "Embed not found", EmbedArtPath: "tests/fixtures/NON_EXISTENT.mp3", FolderIDs: []string{"f1"}}
 		alOnlyExternal = model.Album{ID: "444", Name: "Only external", FolderIDs: []string{"f1"}, Discs: model.Discs{1: "", 2: ""}}
@@ -146,13 +150,61 @@ var _ = Describe("Artwork", func() {
 				Entry(nil, " embedded , front.* , cover.*,folder.*", "tests/fixtures/artist/an-album/test.mp3"),
 			)
 		})
+		Context("LastUpdated", func() {
+			// Regression test for #5377: LastUpdated feeds the HTTP Last-Modified header.
+			// It must return max(album.UpdatedAt, ImagesUpdatedAt) so browsers revalidate
+			// cached cover art when only the image file changes.
+			now := time.Now().Truncate(time.Second)
+			DescribeTable("returns the max of album.UpdatedAt and ImagesUpdatedAt",
+				func(albumUpdatedAt, imagesUpdatedAt, expected time.Time) {
+					album := model.Album{ID: "al1", UpdatedAt: albumUpdatedAt}
+					folderRepo.result = []model.Folder{{ImagesUpdatedAt: imagesUpdatedAt}}
+					ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{album})
+
+					ar, err := newAlbumArtworkReader(ctx, aw, album.CoverArtID(), nil)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(ar.LastUpdated()).To(Equal(expected))
+				},
+				Entry("album newer than images", now, now.Add(-1*time.Hour), now),
+				Entry("images newer than album", now.Add(-24*time.Hour), now.Add(-1*time.Hour), now.Add(-1*time.Hour)),
+				Entry("equal timestamps", now, now, now),
+			)
+		})
+	})
+	Describe("discArtworkReader", func() {
+		Context("LastUpdated", func() {
+			// Regression test for #5377: same bug as albumArtworkReader — disc covers
+			// must also revalidate when the image file changes, not only when media files do.
+			now := time.Now().Truncate(time.Second)
+			DescribeTable("returns the max of album.UpdatedAt and ImagesUpdatedAt",
+				func(albumUpdatedAt, imagesUpdatedAt, expected time.Time) {
+					album := model.Album{ID: "al1", UpdatedAt: albumUpdatedAt}
+					folderRepo.result = []model.Folder{{ImagesUpdatedAt: imagesUpdatedAt}}
+					ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{album})
+					ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+						{ID: "mf1", AlbumID: "al1", DiscNumber: 1, Path: "tests/fixtures/test.mp3"},
+					})
+
+					artID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID("al1", 1), nil)
+					dr, err := newDiscArtworkReader(ctx, aw, artID)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(dr.LastUpdated()).To(Equal(expected))
+				},
+				Entry("album newer than images", now, now.Add(-1*time.Hour), now),
+				Entry("images newer than album", now.Add(-24*time.Hour), now.Add(-1*time.Hour), now.Add(-1*time.Hour)),
+				Entry("equal timestamps", now, now, now),
+			)
+		})
 	})
 	Describe("artistArtworkReader", func() {
 		Context("Multiple covers", func() {
 			BeforeEach(func() {
+				repoRoot, err := os.Getwd()
+				Expect(err).ToNot(HaveOccurred())
 				folderRepo.result = []model.Folder{{
-					Path:       "tests/fixtures/artist/an-album",
-					ImageFiles: []string{"artist.png"},
+					LibraryPath: testFileLibPath(repoRoot),
+					Path:        "tests/fixtures/artist/an-album",
+					ImageFiles:  []string{"artist.png"},
 				}}
 				ds.Artist(ctx).(*tests.MockArtistRepo).SetData(model.Artists{
 					arMultipleCovers,
@@ -171,7 +223,7 @@ var _ = Describe("Artwork", func() {
 					Expect(err).ToNot(HaveOccurred())
 					_, path, err := aw.Reader(ctx)
 					Expect(err).ToNot(HaveOccurred())
-					Expect(path).To(Equal(expected))
+					Expect(filepath.ToSlash(path)).To(HaveSuffix(expected))
 				},
 				Entry(nil, " folder.* , artist.*,album/artist.*", "tests/fixtures/artist/artist.jpg"),
 				Entry(nil, "album/artist.*, folder.*,artist.*", "tests/fixtures/artist/an-album/artist.png"),
@@ -380,6 +432,69 @@ var _ = Describe("Artwork", func() {
 			})
 		})
 		When("Square is false", func() {
+			It("returns PNG if original image is a PNG", func() {
+				conf.Server.CoverArtPriority = "front.png"
+				r, _, err := aw.Get(context.Background(), alMultipleCovers.CoverArtID(), 15, false)
+				Expect(err).ToNot(HaveOccurred())
+
+				img, format, err := image.Decode(r)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(format).To(Equal("png"))
+				Expect(img.Bounds().Size().X).To(Equal(15))
+				Expect(img.Bounds().Size().Y).To(Equal(15))
+			})
+			It("returns JPEG if original image is not a PNG", func() {
+				conf.Server.CoverArtPriority = "cover.jpg"
+				r, _, err := aw.Get(context.Background(), alMultipleCovers.CoverArtID(), 200, false)
+				Expect(err).ToNot(HaveOccurred())
+
+				img, format, err := image.Decode(r)
+				Expect(format).To(Equal("jpeg"))
+				Expect(err).ToNot(HaveOccurred())
+				Expect(img.Bounds().Size().X).To(Equal(200))
+				Expect(img.Bounds().Size().Y).To(Equal(200))
+			})
+		})
+		When("When square is true", func() {
+			var alCover model.Album
+
+			DescribeTable("resize",
+				func(srcFormat string, expectedFormat string, landscape bool, size int) {
+					coverFileName := "cover." + srcFormat
+					dirName := createImage(srcFormat, landscape, size)
+					alCover = model.Album{
+						ID:        "444",
+						Name:      "Only external",
+						FolderIDs: []string{"tmp"},
+					}
+					folderRepo.result = []model.Folder{{ImageFiles: []string{coverFileName}}}
+					rootLibRepo := &tests.MockLibraryRepo{}
+					rootLibRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(dirName)}})
+					ds.(*tests.MockDataStore).MockedLibrary = rootLibRepo
+					ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
+						alCover,
+					})
+
+					conf.Server.CoverArtPriority = coverFileName
+					r, _, err := aw.Get(context.Background(), alCover.CoverArtID(), size, true)
+					Expect(err).ToNot(HaveOccurred())
+
+					img, format, err := image.Decode(r)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(format).To(Equal(expectedFormat))
+					Expect(img.Bounds().Size().X).To(Equal(size))
+					Expect(img.Bounds().Size().Y).To(Equal(size))
+				},
+				Entry("portrait png image", "png", "png", false, 200),
+				Entry("landscape png image", "png", "png", true, 200),
+				Entry("portrait jpg image", "jpg", "png", false, 200),
+				Entry("landscape jpg image", "jpg", "png", true, 200),
+			)
+		})
+		When("EnableWebPEncoding is true and square is false", func() {
+			BeforeEach(func() {
+				conf.Server.EnableWebPEncoding = true
+			})
 			It("returns WebP even if original image is a PNG", func() {
 				conf.Server.CoverArtPriority = "front.png"
 				r, _, err := aw.Get(context.Background(), alMultipleCovers.CoverArtID(), 15, false)
@@ -403,51 +518,18 @@ var _ = Describe("Artwork", func() {
 				Expect(img.Bounds().Size().Y).To(Equal(200))
 			})
 		})
-		When("When square is true", func() {
-			var alCover model.Album
-
-			DescribeTable("resize",
-				func(srcFormat string, expectedFormat string, landscape bool, size int) {
-					coverFileName := "cover." + srcFormat
-					dirName := createImage(srcFormat, landscape, size)
-					alCover = model.Album{
-						ID:        "444",
-						Name:      "Only external",
-						FolderIDs: []string{"tmp"},
-					}
-					folderRepo.result = []model.Folder{{Path: dirName, ImageFiles: []string{coverFileName}}}
-					ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
-						alCover,
-					})
-
-					conf.Server.CoverArtPriority = coverFileName
-					r, _, err := aw.Get(context.Background(), alCover.CoverArtID(), size, true)
-					Expect(err).ToNot(HaveOccurred())
-
-					img, format, err := image.Decode(r)
-					Expect(err).ToNot(HaveOccurred())
-					Expect(format).To(Equal(expectedFormat))
-					Expect(img.Bounds().Size().X).To(Equal(size))
-					Expect(img.Bounds().Size().Y).To(Equal(size))
-				},
-				Entry("portrait png image", "png", "webp", false, 200),
-				Entry("landscape png image", "png", "webp", true, 200),
-				Entry("portrait jpg image", "jpg", "webp", false, 200),
-				Entry("landscape jpg image", "jpg", "webp", true, 200),
-			)
-		})
-		When("DevJpegCoverArt is true and square is false", func() {
+		When("EnableWebPEncoding is false and square is false", func() {
 			BeforeEach(func() {
-				conf.Server.DevJpegCoverArt = true
+				conf.Server.EnableWebPEncoding = false
 			})
-			It("returns JPEG even if original image is a PNG", func() {
+			It("returns PNG if original image is a PNG", func() {
 				conf.Server.CoverArtPriority = "front.png"
 				r, _, err := aw.Get(context.Background(), alMultipleCovers.CoverArtID(), 15, false)
 				Expect(err).ToNot(HaveOccurred())
 
 				img, format, err := image.Decode(r)
 				Expect(err).ToNot(HaveOccurred())
-				Expect(format).To(Equal("jpeg"))
+				Expect(format).To(Equal("png"))
 				Expect(img.Bounds().Size().X).To(Equal(15))
 				Expect(img.Bounds().Size().Y).To(Equal(15))
 			})
@@ -463,11 +545,11 @@ var _ = Describe("Artwork", func() {
 				Expect(img.Bounds().Size().Y).To(Equal(200))
 			})
 		})
-		When("DevJpegCoverArt is true and square is true", func() {
+		When("EnableWebPEncoding is false and square is true", func() {
 			var alCover model.Album
 
 			BeforeEach(func() {
-				conf.Server.DevJpegCoverArt = true
+				conf.Server.EnableWebPEncoding = false
 			})
 			It("returns PNG for square mode", func() {
 				dirName := createImage("png", false, 200)
@@ -476,7 +558,10 @@ var _ = Describe("Artwork", func() {
 					Name:      "Only external",
 					FolderIDs: []string{"tmp"},
 				}
-				folderRepo.result = []model.Folder{{Path: dirName, ImageFiles: []string{"cover.png"}}}
+				folderRepo.result = []model.Folder{{ImageFiles: []string{"cover.png"}}}
+				rootLibRepo := &tests.MockLibraryRepo{}
+				rootLibRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(dirName)}})
+				ds.(*tests.MockDataStore).MockedLibrary = rootLibRepo
 				ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{alCover})
 
 				conf.Server.CoverArtPriority = "cover.png"

core/artwork/artwork_suite_test.go

@@ -1,9 +1,17 @@
 package artwork
 
 import (
+	"io/fs"
+	"net/url"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
 	"testing"
 
+	"github.com/navidrome/navidrome/core/storage"
 	"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 +23,49 @@ func TestArtwork(t *testing.T) {
 	RegisterFailHandler(Fail)
 	RunSpecs(t, "Artwork Suite")
 }
+
+// osDirFS wraps os.DirFS as a storage.MusicFS for integration tests.
+// ReadTags is not used by albumArtworkReader, so it is left as a stub.
+type osDirFS struct{ fs.FS }
+
+func (o osDirFS) ReadTags(...string) (map[string]metadata.Info, error) { return nil, nil }
+
+// testFileScheme is the URL scheme registered to expose a tempdir as a
+// storage.MusicFS for artwork integration tests.
+const testFileScheme = "testfile"
+
+// testFileLibPath builds a `testfile://` library URL for the given absolute
+// filesystem path. On Windows, the native path (e.g. `C:\foo`) has no leading
+// slash after ToSlash, which makes url.Parse treat the drive letter as a
+// host. We prepend a `/` so parsing yields `u.Path == /C:/foo`, and the
+// registered constructor below strips that leading slash back off.
+func testFileLibPath(absPath string) string {
+	p := filepath.ToSlash(absPath)
+	if !strings.HasPrefix(p, "/") {
+		p = "/" + p
+	}
+	return testFileScheme + "://" + p
+}
+
+func init() {
+	// Register the testfile storage scheme (os.DirFS-backed MusicFS). Used by
+	// integration tests that need real files but not the taglib extractor.
+	storage.Register(testFileScheme, func(u url.URL) storage.Storage {
+		root := u.Path
+		// Undo the leading slash added by testFileLibPath on Windows so that
+		// os.Stat / os.DirFS receive a native path like `C:\foo`.
+		if runtime.GOOS == "windows" && len(root) >= 3 && root[0] == '/' && root[2] == ':' {
+			root = root[1:]
+		}
+		return &osDirStorage{root: filepath.FromSlash(root)}
+	})
+}
+
+type osDirStorage struct{ root string }
+
+func (s *osDirStorage) FS() (storage.MusicFS, error) {
+	if _, err := os.Stat(s.root); err != nil {
+		return nil, err
+	}
+	return osDirFS{os.DirFS(s.root)}, nil
+}

core/artwork/cache_warmer.go

@@ -10,7 +10,6 @@ import (
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -24,7 +23,7 @@ type CacheWarmer interface {
 
 // NewCacheWarmer creates a new CacheWarmer instance. The CacheWarmer will pre-cache Artwork images in the background
 // to speed up the response time when the image is requested by the UI. The cache is pre-populated with the original
-// image size, as well as the size defined in the UICoverArtSize constant.
+// image size, as well as the size defined by the UICoverArtSize config option.
 func NewCacheWarmer(artwork Artwork, cache cache.FileCache) CacheWarmer {
 	// If image cache is disabled, return a NOOP implementation
 	if conf.Server.ImageCacheSize == "0" || !conf.Server.EnableArtworkPrecache {
@@ -38,10 +37,11 @@ func NewCacheWarmer(artwork Artwork, cache cache.FileCache) CacheWarmer {
 	}
 
 	a := &cacheWarmer{
-		artwork:    artwork,
-		cache:      cache,
-		buffer:     make(map[model.ArtworkID]struct{}),
-		wakeSignal: make(chan struct{}, 1),
+		artwork:      artwork,
+		cache:        cache,
+		buffer:       make(map[model.ArtworkID]struct{}),
+		wakeSignal:   make(chan struct{}, 1),
+		coverArtSize: conf.Server.UICoverArtSize,
 	}
 
 	// Create a context with a fake admin user, to be able to pre-cache Playlist CoverArts
@@ -51,11 +51,12 @@ func NewCacheWarmer(artwork Artwork, cache cache.FileCache) CacheWarmer {
 }
 
 type cacheWarmer struct {
-	artwork    Artwork
-	buffer     map[model.ArtworkID]struct{}
-	mutex      sync.Mutex
-	cache      cache.FileCache
-	wakeSignal chan struct{}
+	artwork      Artwork
+	buffer       map[model.ArtworkID]struct{}
+	mutex        sync.Mutex
+	cache        cache.FileCache
+	wakeSignal   chan struct{}
+	coverArtSize int
 }
 
 func (a *cacheWarmer) PreCache(artID model.ArtworkID) {
@@ -142,16 +143,14 @@ func (a *cacheWarmer) doCacheImage(ctx context.Context, id model.ArtworkID) erro
 	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
 	defer cancel()
 
-	for _, size := range consts.CacheWarmerImageSizes {
-		r, _, err := a.artwork.Get(ctx, id, size, true)
-		if err != nil {
-			return fmt.Errorf("caching id='%s', size=%d: %w", id, size, err)
-		}
-		_, err = io.Copy(io.Discard, r)
-		r.Close()
-		return err
+	size := a.coverArtSize
+	r, _, err := a.artwork.Get(ctx, id, size, true)
+	if err != nil {
+		return fmt.Errorf("caching id='%s', size=%d: %w", id, size, err)
 	}
-	return nil
+	_, err = io.Copy(io.Discard, r)
+	r.Close()
+	return err
 }
 
 func NoopCacheWarmer() CacheWarmer {

core/artwork/cache_warmer_test.go

@@ -12,7 +12,6 @@ import (
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
-	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/cache"
 	. "github.com/onsi/ginkgo/v2"
@@ -182,7 +181,7 @@ var _ = Describe("CacheWarmer", func() {
 
 			Eventually(func() []int {
 				return aw.getCachedSizes()
-			}).Should(ContainElements(consts.UICoverArtSize))
+			}).Should(ContainElements(conf.Server.UICoverArtSize))
 		})
 	})
 })

core/artwork/e2e/album_test.go

@@ -0,0 +1,352 @@
+package artworke2e_test
+
+import (
+	"testing/fstest"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+const (
+	defaultCoverPriority = "cover.*, folder.*, front.*, embedded, external"
+	defaultDiscPriority  = "disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded"
+)
+
+var _ = Describe("Album artwork resolution", func() {
+	BeforeEach(func() {
+		setupHarness()
+	})
+
+	When("an album has a single folder with cover.jpg at the album root", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── cover.jpg            ← matched by cover.*
+		It("returns the album-root cover", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/cover.jpg":      imageFile("album-root"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
+		})
+	})
+
+	// Bug 2 variant: cover.* basenames tie across album-root and per-disc folders;
+	// compareImageFiles' lexicographic full-path tiebreaker ranks disc-subfolder
+	// files first.
+	When("a multi-disc album has a cover.jpg at the album root and per-disc covers", func() {
+		// Artist/
+		// └── Album/
+		//     ├── CD1/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── cover.jpg        ← currently wins (bug)
+		//     ├── CD2/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── cover.jpg
+		//     └── cover.jpg            ← should win (album-root fallback)
+		It("prefers the album-root cover over per-disc covers", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "Track CD1"),
+				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "Track CD2"),
+				"Artist/Album/cover.jpg":          imageFile("album-root"),
+				"Artist/Album/CD1/cover.jpg":      imageFile("disc1"),
+				"Artist/Album/CD2/cover.jpg":      imageFile("disc2"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(al.FolderIDs).To(HaveLen(2),
+				"sanity check: scanner should treat the two disc subfolders as one multi-disc album")
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
+		})
+	})
+
+	// Bug 2: folder.jpg basenames tie across album-root and per-disc folders;
+	// the lexicographic full-path tiebreaker in compareImageFiles ranks
+	// "Artist/Album/CD1/folder.jpg" ahead of "Artist/Album/folder.jpg".
+	When("a multi-disc album has folder.jpg at the album root AND in each disc subfolder", func() {
+		// Artist/
+		// └── Album/
+		//     ├── CD1/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── folder.jpg       ← currently wins (bug)
+		//     ├── CD2/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── folder.jpg
+		//     └── folder.jpg           ← should win (album-root fallback)
+		It("prefers the album-root folder.jpg over per-disc folder.jpg", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "Track CD1"),
+				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "Track CD2"),
+				"Artist/Album/folder.jpg":         imageFile("album-root"),
+				"Artist/Album/CD1/folder.jpg":     imageFile("disc1"),
+				"Artist/Album/CD2/folder.jpg":     imageFile("disc2"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
+		})
+	})
+
+	// Bug 1: commonParentFolder's `len(folders) < 2` guard skips the parent-folder
+	// lookup whenever an album lives entirely under a single subfolder, so an
+	// album-root cover is never considered.
+	When("an album lives entirely under a single disc subfolder with cover.jpg at the parent", func() {
+		// Artist/
+		// └── Album/
+		//     ├── disc1/
+		//     │   └── 01 - Track.mp3
+		//     └── cover.jpg            ← should win (parent-folder fallback, currently ignored — bug)
+		It("uses the parent-folder cover for single-disc-subfolder albums", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/disc1/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/cover.jpg":            imageFile("album-root"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
+		})
+	})
+
+	When("CoverArtPriority puts embedded first and the album has both embedded and external art", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3      ← has embedded picture (wins via "embedded")
+		//     └── cover.jpg
+		It("returns the embedded image", func() {
+			conf.Server.CoverArtPriority = "embedded, cover.*, folder.*, front.*, external"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"has_picture": "true"}),
+				"Artist/Album/cover.jpg":      imageFile("external"),
+			})
+			scan()
+			// Swap in real MP3 bytes so libFS.Open returns a taglib-readable stream.
+			replaceWithRealMP3("Artist/Album/01 - Track.mp3")
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(embeddedArtBytes))
+		})
+	})
+
+	When("CoverArtPriority lists external first but no external file is present", func() {
+		// Artist/
+		// └── Album/
+		//     └── 01 - Track.mp3      ← has embedded picture (falls through to "embedded")
+		It("falls through to embedded artwork", func() {
+			conf.Server.CoverArtPriority = "external, embedded"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"has_picture": "true"}),
+			})
+			scan()
+			replaceWithRealMP3("Artist/Album/01 - Track.mp3")
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(embeddedArtBytes))
+		})
+	})
+
+	When("the only cover file uses uppercase extension and a different case in its name", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── Cover.JPG            ← matched case-insensitively by cover.*
+		It("matches case-insensitively against cover.*", func() {
+			conf.Server.CoverArtPriority = "cover.*, folder.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/Cover.JPG":      imageFile("case-insensitive"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("case-insensitive")))
+		})
+	})
+
+	When("two cover files have basenames that tie under the natural-sort tiebreaker", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     ├── cover.jpg            ← wins (no numeric suffix)
+		//     └── cover.1.jpg
+		It("prefers the file without a numeric suffix", func() {
+			conf.Server.CoverArtPriority = "cover.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/cover.jpg":      imageFile("primary"),
+				"Artist/Album/cover.1.jpg":    imageFile("secondary"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("primary")))
+		})
+	})
+
+	When("the album has no cover and CoverArtPriority lists only file patterns", func() {
+		// Artist/
+		// └── Album/
+		//     └── 01 - Track.mp3       (no image files — returns ErrUnavailable)
+		It("returns ErrUnavailable", func() {
+			conf.Server.CoverArtPriority = "cover.*, folder.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+			})
+			scan()
+
+			al := firstAlbum()
+			_, err := readArtworkOrErr(model.NewArtworkID(model.KindAlbumArtwork, al.ID, &al.UpdatedAt))
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
+	// Doc scenarios from:
+	// https://www.navidrome.org/docs/usage/library/artwork/#albums
+	// Default CoverArtPriority is "cover.*, folder.*, front.*, embedded, external".
+	When("only folder.jpg is present (cover.* and front.* missing)", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── folder.jpg           ← matched by folder.*
+		It("falls through to folder.jpg", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/folder.jpg":     imageFile("folder"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("folder")))
+		})
+	})
+
+	When("only front.jpg is present (cover.* and folder.* missing)", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── front.jpg            ← matched by front.*
+		It("falls through to front.jpg", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/front.jpg":      imageFile("front"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("front")))
+		})
+	})
+
+	When("cover.*, folder.*, and front.* all exist in the same folder", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     ├── cover.jpg            ← wins (cover.* is first in priority)
+		//     ├── folder.jpg
+		//     └── front.jpg
+		It("prefers cover.* (first in CoverArtPriority)", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/cover.jpg":      imageFile("cover"),
+				"Artist/Album/folder.jpg":     imageFile("folder"),
+				"Artist/Album/front.jpg":      imageFile("front"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("cover")))
+		})
+	})
+
+	When("only folder.* and front.* exist (priority order check)", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     ├── folder.jpg           ← wins (folder.* comes before front.*)
+		//     └── front.jpg
+		It("prefers folder.* over front.*", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/folder.jpg":     imageFile("folder"),
+				"Artist/Album/front.jpg":      imageFile("front"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("folder")))
+		})
+	})
+
+	When("three cover files tie by basename and differ only by numeric suffix", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     ├── cover.jpg            ← wins (no numeric suffix)
+		//     ├── cover.1.jpg
+		//     └── cover.2.jpg
+		It("selects the unsuffixed file first regardless of numeric-suffix order", func() {
+			conf.Server.CoverArtPriority = "cover.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/cover.2.jpg":    imageFile("second"),
+				"Artist/Album/cover.jpg":      imageFile("primary"),
+				"Artist/Album/cover.1.jpg":    imageFile("first"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("primary")))
+		})
+	})
+
+	When("CoverArtPriority contains an unknown pattern before a matching one", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── cover.jpg            ← wins (unknown "bogus.*" is skipped)
+		It("skips the unknown pattern and falls through to the matching one", func() {
+			conf.Server.CoverArtPriority = "bogus.*, cover.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/cover.jpg":      imageFile("cover"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("cover")))
+		})
+	})
+
+	When("embedded is first in CoverArtPriority but the track has no embedded art", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3       (no embedded picture)
+		//     └── cover.jpg            ← wins (embedded skipped, falls through)
+		It("falls through to the next priority entry", func() {
+			conf.Server.CoverArtPriority = "embedded, cover.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/cover.jpg":      imageFile("cover"),
+			})
+			scan()
+
+			al := firstAlbum()
+			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("cover")))
+		})
+	})
+})

core/artwork/e2e/artist_test.go

@@ -0,0 +1,167 @@
+package artworke2e_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing/fstest"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// Doc reference:
+// https://www.navidrome.org/docs/usage/library/artwork/#artists
+// Default ArtistArtPriority is "artist.*, album/artist.*, external".
+var _ = Describe("Artist artwork resolution", func() {
+	BeforeEach(func() {
+		setupHarness()
+	})
+
+	When("the artist folder contains an artist.jpg", func() {
+		// Artist/
+		// ├── artist.jpg               ← matched by artist.*
+		// └── Album/
+		//     └── 01 - Track.mp3
+		It("returns the artist.* image from the artist folder", func() {
+			conf.Server.ArtistArtPriority = "artist.*, album/artist.*, external"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"albumartist": "Artist"}),
+				"Artist/artist.jpg":           imageFile("artist-folder"),
+			})
+			scan()
+
+			ar := soleArtist()
+			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
+			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-folder")))
+		})
+	})
+
+	When("artist.* only exists inside an album folder", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── artist.jpg           ← matched by album/artist.*
+		It("falls through to album/artist.* and returns that image", func() {
+			conf.Server.ArtistArtPriority = "artist.*, album/artist.*, external"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"albumartist": "Artist"}),
+				"Artist/Album/artist.jpg":     imageFile("album-artist"),
+			})
+			scan()
+
+			ar := soleArtist()
+			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
+			Expect(readArtwork(artID)).To(Equal(imageBytes("album-artist")))
+		})
+	})
+
+	When("both the artist folder and an album folder have an artist.* image", func() {
+		// Artist/
+		// ├── artist.jpg               ← wins (artist.* before album/artist.*)
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── artist.jpg
+		It("prefers the artist-folder image (artist.* comes before album/artist.*)", func() {
+			conf.Server.ArtistArtPriority = "artist.*, album/artist.*, external"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"albumartist": "Artist"}),
+				"Artist/artist.jpg":           imageFile("artist-folder"),
+				"Artist/Album/artist.jpg":     imageFile("album-artist"),
+			})
+			scan()
+
+			ar := soleArtist()
+			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
+			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-folder")))
+		})
+	})
+
+	When("an artist has an uploaded image and a matching artist.* file", func() {
+		// <DataFolder>/
+		// └── artwork/
+		//     └── artist/
+		//         └── <id>_upload.jpg  ← wins (uploaded image beats the priority chain)
+		// Library:
+		// Artist/
+		// ├── artist.jpg               (ignored — uploaded image comes first)
+		// └── Album/
+		//     └── 01 - Track.mp3
+		It("prefers the uploaded image over any priority-chain match", func() {
+			conf.Server.ArtistArtPriority = "artist.*, album/artist.*, external"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"albumartist": "Artist"}),
+				"Artist/artist.jpg":           imageFile("artist-folder"),
+			})
+			scan()
+			ar := soleArtist()
+
+			uploaded := ar.ID + "_upload.jpg"
+			writeUploadedImage(consts.EntityArtist, uploaded, imageBytes("artist-uploaded"))
+			ar.UploadedImage = uploaded
+			Expect(ds.Artist(ctx).Put(&ar)).To(Succeed())
+
+			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
+			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-uploaded")))
+		})
+	})
+
+	When("ArtistArtPriority uses album/<arbitrary pattern> (not just album/artist.*)", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── artist.jpg            ← matched by album/artist.*
+		It("resolves the pattern against the artist's album image files", func() {
+			conf.Server.ArtistArtPriority = "album/artist.*, external"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"albumartist": "Artist"}),
+				"Artist/Album/artist.jpg":     imageFile("album-artist"),
+			})
+			scan()
+
+			ar := soleArtist()
+			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
+			Expect(readArtwork(artID)).To(Equal(imageBytes("album-artist")))
+		})
+	})
+
+	When("ArtistArtPriority starts with image-folder and ArtistImageFolder has a name-matching image", func() {
+		// <ArtistImageFolder>/
+		// └── Artist.jpg               ← matched by artist name (image-folder source)
+		// Library:
+		// Artist/
+		// └── Album/
+		//     └── 01 - Track.mp3       (no artist.* present in library)
+		It("returns the image from the configured artist image folder", func() {
+			imgFolder := GinkgoT().TempDir()
+			Expect(os.WriteFile(filepath.Join(imgFolder, "Artist.jpg"), imageBytes("image-folder"), 0600)).To(Succeed())
+			conf.Server.ArtistImageFolder = imgFolder
+			conf.Server.ArtistArtPriority = "image-folder, artist.*, album/artist.*"
+
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"albumartist": "Artist"}),
+			})
+			scan()
+
+			ar := soleArtist()
+			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
+			Expect(readArtwork(artID)).To(Equal(imageBytes("image-folder")))
+		})
+	})
+})
+
+func soleArtist() model.Artist {
+	GinkgoHelper()
+	artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.Eq{"artist.name": "Artist"},
+	})
+	Expect(err).ToNot(HaveOccurred())
+	if len(artists) == 0 {
+		Fail("sole artist not found")
+		return model.Artist{}
+	}
+	return artists[0]
+}

core/artwork/e2e/disc_test.go

@@ -0,0 +1,276 @@
+package artworke2e_test
+
+import (
+	"testing/fstest"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Disc artwork resolution", func() {
+	BeforeEach(func() {
+		setupHarness()
+	})
+
+	When("the album is single-disc with a disc1.jpg in the only folder", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── disc1.jpg            ← matched by disc*.*
+		It("returns the disc1.jpg image (matched as disc*.*)", func() {
+			conf.Server.DiscArtPriority = "disc*.*, cd*.*, cover.*, folder.*, front.*, embedded"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/disc1.jpg":      imageFile("disc1-image"),
+			})
+			scan()
+
+			al := firstAlbum()
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
+			Expect(readArtwork(discID)).To(Equal(imageBytes("disc1-image")))
+		})
+	})
+
+	When("the album has no per-disc image and no album cover", func() {
+		// Artist/
+		// └── Album/
+		//     └── 01 - Track.mp3       (no disc or album art — returns ErrUnavailable)
+		It("returns ErrUnavailable for the disc lookup", func() {
+			conf.Server.DiscArtPriority = "disc*.*, cd*.*"
+			conf.Server.CoverArtPriority = "cover.*, folder.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+			})
+			scan()
+
+			al := firstAlbum()
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
+			_, err := readArtworkOrErr(discID)
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
+	When("the album has no per-disc image but has an album cover", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── cover.jpg            ← album-level fallback (no disc art present)
+		It("falls back to the album cover", func() {
+			conf.Server.DiscArtPriority = "disc*.*, cd*.*"
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/cover.jpg":      imageFile("album-cover"),
+			})
+			scan()
+
+			al := firstAlbum()
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
+			Expect(readArtwork(discID)).To(Equal(imageBytes("album-cover")))
+		})
+	})
+
+	When("multiple disc images exist in the same folder (disc1 vs disc10)", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     ├── disc1.jpg            ← matches request for disc 1
+		//     └── disc10.jpg
+		It("matches the requested disc number, not a higher-numbered one", func() {
+			conf.Server.DiscArtPriority = "disc*.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/disc1.jpg":      imageFile("disc-one"),
+				"Artist/Album/disc10.jpg":     imageFile("disc-ten"),
+			})
+			scan()
+
+			al := firstAlbum()
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
+			Expect(readArtwork(discID)).To(Equal(imageBytes("disc-one")))
+		})
+	})
+
+	When("a multi-disc album has per-disc covers", func() {
+		// Artist/
+		// └── Album/
+		//     ├── CD1/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── disc1.jpg        ← matches request for disc 1
+		//     └── CD2/
+		//         ├── 01 - Track.mp3
+		//         └── disc2.jpg        ← matches request for disc 2
+		It("returns the requested disc's image", func() {
+			conf.Server.DiscArtPriority = "disc*.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
+				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
+				"Artist/Album/CD1/disc1.jpg":      imageFile("disc-1"),
+				"Artist/Album/CD2/disc2.jpg":      imageFile("disc-2"),
+			})
+			scan()
+
+			al := firstAlbum()
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 2), &al.UpdatedAt)
+			Expect(readArtwork(discID)).To(Equal(imageBytes("disc-2")))
+		})
+	})
+
+	// Doc scenarios from:
+	// https://www.navidrome.org/docs/usage/library/artwork/#disc-cover-art
+	// Default DiscArtPriority is "disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded".
+	When("a disc subfolder has a cd2.png image", func() {
+		// Artist/
+		// └── Album/
+		//     ├── CD1/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── disc1.jpg
+		//     └── CD2/
+		//         ├── 01 - Track.mp3
+		//         └── cd2.png          ← matched by cd*.* for disc 2
+		It("matches via the cd*.* pattern", func() {
+			conf.Server.DiscArtPriority = defaultDiscPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
+				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
+				"Artist/Album/CD1/disc1.jpg":      imageFile("disc-1"),
+				"Artist/Album/CD2/cd2.png":        imageFile("cd-2"),
+			})
+			scan()
+
+			al := firstAlbum()
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 2), &al.UpdatedAt)
+			Expect(readArtwork(discID)).To(Equal(imageBytes("cd-2")))
+		})
+	})
+
+	When("a disc subfolder has cover.jpg but no disc*.*/cd*.* image", func() {
+		// Artist/
+		// └── Album/
+		//     ├── CD1/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── cover.jpg        ← matched by cover.* inside disc folder
+		//     └── CD2/
+		//         ├── 01 - Track.mp3
+		//         └── cover.jpg
+		It("falls through to cover.* inside the disc folder", func() {
+			conf.Server.DiscArtPriority = defaultDiscPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
+				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
+				"Artist/Album/CD1/cover.jpg":      imageFile("disc1-cover"),
+				"Artist/Album/CD2/cover.jpg":      imageFile("disc2-cover"),
+			})
+			scan()
+
+			al := firstAlbum()
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
+			Expect(readArtwork(discID)).To(Equal(imageBytes("disc1-cover")))
+		})
+	})
+
+	When("DiscArtPriority is the empty string", func() {
+		// Artist/
+		// └── Album/
+		//     ├── CD1/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── disc1.jpg        (ignored — DiscArtPriority is empty)
+		//     ├── CD2/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── cd2.png          (ignored — DiscArtPriority is empty)
+		//     └── cover.jpg            ← used for every disc (album-level fallback)
+		It("skips every disc-level source and returns the album cover", func() {
+			conf.Server.DiscArtPriority = ""
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
+				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
+				"Artist/Album/CD1/disc1.jpg":      imageFile("disc-1"),
+				"Artist/Album/CD2/cd2.png":        imageFile("cd-2"),
+				"Artist/Album/cover.jpg":          imageFile("album-cover"),
+			})
+			scan()
+
+			al := firstAlbum()
+			for _, n := range []int{1, 2} {
+				discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, n), &al.UpdatedAt)
+				Expect(readArtwork(discID)).To(Equal(imageBytes("album-cover")),
+					"disc %d should use the album cover when DiscArtPriority is empty", n)
+			}
+		})
+	})
+
+	When("the documented multi-disc layout is used (disc1.jpg + cd2.png + album-root cover.jpg)", func() {
+		// Artist/
+		// └── Album/
+		//     ├── disc1/
+		//     │   ├── disc1.jpg        ← matched by disc*.* for disc 1
+		//     │   ├── 01 - Track.mp3
+		//     │   └── 02 - Track.mp3
+		//     ├── disc2/
+		//     │   ├── cd2.png          ← matched by cd*.* for disc 2
+		//     │   ├── 01 - Track.mp3
+		//     │   └── 02 - Track.mp3
+		//     └── cover.jpg            (album-level fallback, unused here)
+		It("matches the per-disc image for each disc", func() {
+			conf.Server.DiscArtPriority = defaultDiscPriority
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/disc1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
+				"Artist/Album/disc1/02 - Track.mp3": trackFile(2, "T2", map[string]any{"disc": "1"}),
+				"Artist/Album/disc2/01 - Track.mp3": trackFile(1, "T3", map[string]any{"disc": "2"}),
+				"Artist/Album/disc2/02 - Track.mp3": trackFile(2, "T4", map[string]any{"disc": "2"}),
+				"Artist/Album/disc1/disc1.jpg":      imageFile("disc-1"),
+				"Artist/Album/disc2/cd2.png":        imageFile("cd-2"),
+				"Artist/Album/cover.jpg":            imageFile("album-root"),
+			})
+			scan()
+
+			al := firstAlbum()
+			disc1ID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
+			disc2ID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 2), &al.UpdatedAt)
+			Expect(readArtwork(disc1ID)).To(Equal(imageBytes("disc-1")))
+			Expect(readArtwork(disc2ID)).To(Equal(imageBytes("cd-2")))
+		})
+	})
+
+	When("discsubtitle keyword matches an image whose stem equals the disc's subtitle", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3       (discsubtitle="Bonus Tracks")
+		//     └── Bonus Tracks.jpg     ← matched by "discsubtitle" keyword
+		It("selects the subtitle-named image", func() {
+			conf.Server.DiscArtPriority = "discsubtitle"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3":   trackFile(1, "T1", map[string]any{"disc": "1", "discsubtitle": "Bonus Tracks"}),
+				"Artist/Album/Bonus Tracks.jpg": imageFile("bonus-tracks"),
+			})
+			scan()
+
+			al := firstAlbum()
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
+			Expect(readArtwork(discID)).To(Equal(imageBytes("bonus-tracks")))
+		})
+	})
+
+	When("discsubtitle is set but no image filename matches the subtitle", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3       (discsubtitle="Bonus Tracks")
+		//     └── cover.jpg            ← wins (discsubtitle has no match, falls through)
+		It("falls through to the next priority entry", func() {
+			conf.Server.DiscArtPriority = "discsubtitle, cover.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1", "discsubtitle": "Bonus Tracks"}),
+				"Artist/Album/cover.jpg":      imageFile("cover"),
+			})
+			scan()
+
+			al := firstAlbum()
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
+			Expect(readArtwork(discID)).To(Equal(imageBytes("cover")))
+		})
+	})
+})

core/artwork/e2e/helpers_test.go

@@ -0,0 +1,184 @@
+package artworke2e_test
+
+import (
+	"bytes"
+	"context"
+	_ "embed"
+	"errors"
+	"hash/fnv"
+	"image"
+	"image/color"
+	"image/png"
+	"io"
+	"maps"
+	"net/url"
+	"os"
+	"path/filepath"
+	"testing/fstest"
+
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/storage/storagetest"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/resources"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"go.senan.xyz/taglib"
+)
+
+// realMP3WithEmbeddedArt is the bytes of the canonical test fixture that
+// contains a valid MP3 stream with an embedded picture. Used in the
+// embedded-art e2e scenarios where FakeFS's JSON-encoded tag data isn't
+// readable by taglib. Swap this into fakeFS.MapFS *after* scanning so the
+// scanner still populates EmbedArtPath via the JSON-tagged track, and the
+// artwork reader gets real bytes when it calls libFS.Open.
+//
+//go:embed testdata/embedded_art.mp3
+var realMP3WithEmbeddedArt []byte
+
+// embeddedArtBytes is the exact image payload that the artwork reader will
+// extract from realMP3WithEmbeddedArt. Computed once via taglib so tests can
+// assert byte-for-byte equality — if this ever differs it means the reader
+// pulled from a different source.
+var embeddedArtBytes = extractEmbeddedArt(realMP3WithEmbeddedArt)
+
+func extractEmbeddedArt(mp3 []byte) []byte {
+	tf, err := taglib.OpenStream(bytes.NewReader(mp3))
+	if err != nil {
+		panic("embedded-art fixture: taglib.OpenStream failed: " + err.Error())
+	}
+	defer tf.Close()
+	images := tf.Properties().Images
+	if len(images) == 0 {
+		panic("embedded-art fixture has no embedded images")
+	}
+	data, err := tf.Image(0)
+	if err != nil || len(data) == 0 {
+		panic("embedded-art fixture: could not read image 0")
+	}
+	return data
+}
+
+// replaceWithRealMP3 swaps the FakeFS entry at the given library-relative
+// path so libFS.Open returns an MP3 stream taglib can parse.
+func replaceWithRealMP3(relPath string) {
+	GinkgoHelper()
+	fakeFS.MapFS[relPath] = &fstest.MapFile{Data: realMP3WithEmbeddedArt}
+}
+
+// placeholderBytes returns the bundled album-placeholder image bytes — the
+// same stream the artwork reader emits when every source falls through.
+func placeholderBytes() []byte {
+	GinkgoHelper()
+	r, err := resources.FS().Open(consts.PlaceholderAlbumArt)
+	Expect(err).ToNot(HaveOccurred())
+	defer r.Close()
+	data, err := io.ReadAll(r)
+	Expect(err).ToNot(HaveOccurred())
+	return data
+}
+
+// writeUploadedImage drops `filename` into <DataFolder>/artwork/<entity>/ with
+// the given bytes, matching the on-disk layout expected by
+// model.UploadedImagePath.
+func writeUploadedImage(entity, filename string, data []byte) {
+	GinkgoHelper()
+	dir := filepath.Dir(model.UploadedImagePath(entity, filename))
+	Expect(os.MkdirAll(dir, 0755)).To(Succeed())
+	Expect(os.WriteFile(filepath.Join(dir, filename), data, 0600)).To(Succeed())
+}
+
+func newNoopFFmpeg() *tests.MockFFmpeg {
+	ff := tests.NewMockFFmpeg("")
+	ff.Error = errors.New("noop")
+	return ff
+}
+
+// trackFile builds a FakeFS MP3 entry with optional tag overrides.
+func trackFile(num int, title string, extra ...map[string]any) *fstest.MapFile {
+	tags := storagetest.Track(num, title)
+	for _, e := range extra {
+		maps.Copy(tags, e)
+	}
+	return storagetest.MP3(tags)
+}
+
+// imageFile builds a label-keyed image entry. The bytes are deterministic
+// per-label so tests can assert which file won.
+func imageFile(label string) *fstest.MapFile {
+	return &fstest.MapFile{Data: []byte("image:" + label)}
+}
+
+// realPNG builds a minimal 2x2 PNG with a color derived from label. Needed by
+// tests that feed the bytes into image.Decode (e.g. playlist tiled covers).
+func realPNG(label string) *fstest.MapFile {
+	img := image.NewRGBA(image.Rect(0, 0, 2, 2))
+	// Derive a deterministic color per label.
+	h := fnv.New32a()
+	_, _ = h.Write([]byte(label))
+	sum := h.Sum32()
+	c := color.RGBA{R: byte(sum), G: byte(sum >> 8), B: byte(sum >> 16), A: 255}
+	for y := range 2 {
+		for x := range 2 {
+			img.Set(x, y, c)
+		}
+	}
+	var buf bytes.Buffer
+	Expect(png.Encode(&buf, img)).To(Succeed())
+	return &fstest.MapFile{Data: buf.Bytes()}
+}
+
+// imageBytes returns the bytes that imageFile(label) writes.
+func imageBytes(label string) []byte { return imageFile(label).Data }
+
+// setLayout populates fakeFS with the given map. Call after setupHarness.
+// All paths must be forward-slash and relative (no leading "/").
+func setLayout(files fstest.MapFS) {
+	GinkgoHelper()
+	fakeFS.SetFiles(files)
+}
+
+func readArtwork(artID model.ArtworkID) []byte {
+	GinkgoHelper()
+	r, _, err := aw.Get(ctx, artID, 0, false)
+	Expect(err).ToNot(HaveOccurred())
+	defer r.Close()
+	b, err := io.ReadAll(r)
+	Expect(err).ToNot(HaveOccurred())
+	return b
+}
+
+func readArtworkOrErr(artID model.ArtworkID) ([]byte, error) {
+	r, _, err := aw.Get(ctx, artID, 0, false)
+	if err != nil {
+		return nil, err
+	}
+	defer r.Close()
+	return io.ReadAll(r)
+}
+
+// noopProvider implements external.Provider with not-found returns so the
+// "external" priority entry never produces a result.
+type noopProvider struct{}
+
+func (n *noopProvider) UpdateAlbumInfo(context.Context, string) (*model.Album, error) {
+	return nil, model.ErrNotFound
+}
+func (n *noopProvider) UpdateArtistInfo(context.Context, string, int, bool) (*model.Artist, error) {
+	return nil, model.ErrNotFound
+}
+func (n *noopProvider) SimilarSongs(context.Context, string, int) (model.MediaFiles, error) {
+	return nil, nil
+}
+func (n *noopProvider) TopSongs(context.Context, string, int) (model.MediaFiles, error) {
+	return nil, nil
+}
+func (n *noopProvider) ArtistImage(context.Context, string) (*url.URL, error) {
+	return nil, model.ErrNotFound
+}
+func (n *noopProvider) AlbumImage(context.Context, string) (*url.URL, error) {
+	return nil, model.ErrNotFound
+}
+
+var _ external.Provider = (*noopProvider)(nil)

core/artwork/e2e/mediafile_test.go

@@ -0,0 +1,110 @@
+package artworke2e_test
+
+import (
+	"testing/fstest"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// Doc reference:
+// https://www.navidrome.org/docs/usage/library/artwork/#mediafiles
+// Navidrome resolves mediafile artwork in this order:
+//  1. Embedded image from the mediafile itself
+//  2. For multi-disc albums, disc-level artwork
+//  3. Album cover art
+//
+// FakeFS cannot synthesize taglib-readable embedded JPEGs, so scenario (1)
+// is covered by the existing embedded-art album tests (which currently
+// Skip under FakeFS). The tests below cover (2) and (3): the fallback
+// chain for tracks without embedded art.
+var _ = Describe("MediaFile artwork fallback", func() {
+	BeforeEach(func() {
+		setupHarness()
+	})
+
+	When("a multi-disc album track has no embedded art", func() {
+		// Artist/
+		// └── Album/
+		//     ├── CD1/
+		//     │   ├── 01 - Track.mp3
+		//     │   └── disc1.jpg
+		//     ├── CD2/
+		//     │   ├── 01 - Track.mp3   ← track requested
+		//     │   └── disc2.jpg        ← wins (disc-level before album-level)
+		//     └── cover.jpg
+		It("falls back to the disc-level artwork (not the album cover)", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			conf.Server.DiscArtPriority = defaultDiscPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
+				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
+				"Artist/Album/CD1/disc1.jpg":      imageFile("disc-1"),
+				"Artist/Album/CD2/disc2.jpg":      imageFile("disc-2"),
+				"Artist/Album/cover.jpg":          imageFile("album-root"),
+			})
+			scan()
+
+			mf := mediafileOn("Artist/Album/CD2/01 - Track.mp3")
+			Expect(readArtwork(mf.CoverArtID())).To(Equal(imageBytes("disc-2")))
+		})
+	})
+
+	When("a single-disc album track has no embedded art", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3       ← track requested
+		//     └── cover.jpg            ← wins (album-level fallback, no disc subfolder)
+		It("falls back to the album cover", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			conf.Server.DiscArtPriority = defaultDiscPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
+				"Artist/Album/cover.jpg":      imageFile("album-cover"),
+			})
+			scan()
+
+			mf := mediafileOn("Artist/Album/01 - Track.mp3")
+			Expect(readArtwork(mf.CoverArtID())).To(Equal(imageBytes("album-cover")))
+		})
+	})
+
+	When("a multi-disc album track has no embedded art and the disc has no disc-level image", func() {
+		// Artist/
+		// └── Album/
+		//     ├── CD1/
+		//     │   └── 01 - Track.mp3
+		//     ├── CD2/
+		//     │   └── 01 - Track.mp3   ← track requested
+		//     └── cover.jpg            ← wins (no disc image → album-level fallback)
+		It("falls through from disc to album cover", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			conf.Server.DiscArtPriority = defaultDiscPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
+				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
+				"Artist/Album/cover.jpg":          imageFile("album-root"),
+			})
+			scan()
+
+			mf := mediafileOn("Artist/Album/CD2/01 - Track.mp3")
+			Expect(readArtwork(mf.CoverArtID())).To(Equal(imageBytes("album-root")))
+		})
+	})
+})
+
+func mediafileOn(relPath string) model.MediaFile {
+	GinkgoHelper()
+	mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.Like{"media_file.path": relPath},
+	})
+	Expect(err).ToNot(HaveOccurred())
+	if len(mfs) == 0 {
+		Fail("mediafile not found: " + relPath)
+		return model.MediaFile{}
+	}
+	return mfs[0]
+}

core/artwork/e2e/playlist_test.go

@@ -0,0 +1,158 @@
+package artworke2e_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing/fstest"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// Playlist artwork resolves in this priority order:
+//  1. Uploaded image (<DataFolder>/artwork/playlist/<file>)
+//  2. Sidecar image next to the .m3u file (same basename, any image ext)
+//  3. ExternalImageURL (http/https requires EnableM3UExternalAlbumArt; local path always allowed)
+//  4. Generated 2x2 tiled cover from the playlist's albums
+//  5. Album placeholder image
+//
+// The library FS is FakeFS, but uploaded/sidecar/local-external images are
+// real files on disk — the reader reads them via os.Open, so the tests
+// place them in a real tempdir under DataFolder.
+var _ = Describe("Playlist artwork resolution", func() {
+	BeforeEach(func() {
+		setupHarness()
+	})
+
+	When("a playlist has an uploaded image", func() {
+		// <DataFolder>/
+		// └── artwork/
+		//     └── playlist/
+		//         └── pl-1_upload.jpg   ← matched by UploadedImagePath() (highest priority)
+		It("returns the uploaded image bytes", func() {
+			writeUploadedImage(consts.EntityPlaylist, "pl-1_upload.jpg", imageBytes("playlist-upload"))
+
+			pl := putPlaylist(model.Playlist{ID: "pl-1", Name: "Test", UploadedImage: "pl-1_upload.jpg"})
+
+			Expect(readArtwork(pl.CoverArtID())).To(Equal(imageBytes("playlist-upload")))
+		})
+	})
+
+	When("a playlist has no uploaded image but a sidecar image beside its .m3u file", func() {
+		// <tempdir>/
+		// ├── MyList.m3u
+		// └── MyList.jpg               ← matched by sidecar (same basename, case-insensitive)
+		It("returns the sidecar image", func() {
+			dir := GinkgoT().TempDir()
+			m3uPath := filepath.Join(dir, "MyList.m3u")
+			Expect(os.WriteFile(m3uPath, []byte("#EXTM3U\n"), 0600)).To(Succeed())
+			Expect(os.WriteFile(filepath.Join(dir, "MyList.jpg"), imageBytes("sidecar"), 0600)).To(Succeed())
+
+			pl := putPlaylist(model.Playlist{ID: "pl-2", Name: "MyList", Path: m3uPath})
+
+			Expect(readArtwork(pl.CoverArtID())).To(Equal(imageBytes("sidecar")))
+		})
+	})
+
+	When("a playlist's sidecar uses a different extension case", func() {
+		// <tempdir>/
+		// ├── MyList.m3u
+		// └── MyList.PNG               ← matched case-insensitively
+		It("matches case-insensitively", func() {
+			dir := GinkgoT().TempDir()
+			m3uPath := filepath.Join(dir, "MyList.m3u")
+			Expect(os.WriteFile(m3uPath, []byte("#EXTM3U\n"), 0600)).To(Succeed())
+			Expect(os.WriteFile(filepath.Join(dir, "MyList.PNG"), imageBytes("sidecar-png"), 0600)).To(Succeed())
+
+			pl := putPlaylist(model.Playlist{ID: "pl-3", Name: "MyList", Path: m3uPath})
+
+			Expect(readArtwork(pl.CoverArtID())).To(Equal(imageBytes("sidecar-png")))
+		})
+	})
+
+	When("a playlist has an ExternalImageURL pointing to a local file", func() {
+		// <tempdir>/
+		// └── cover.jpg                ← absolute path stored in ExternalImageURL
+		It("returns the local file regardless of EnableM3UExternalAlbumArt", func() {
+			conf.Server.EnableM3UExternalAlbumArt = false // local paths bypass the toggle
+			dir := GinkgoT().TempDir()
+			imgPath := filepath.Join(dir, "cover.jpg")
+			Expect(os.WriteFile(imgPath, imageBytes("external-local"), 0600)).To(Succeed())
+
+			pl := putPlaylist(model.Playlist{ID: "pl-4", Name: "WithExt", ExternalImageURL: imgPath})
+
+			Expect(readArtwork(pl.CoverArtID())).To(Equal(imageBytes("external-local")))
+		})
+	})
+
+	When("a playlist has an http(s) ExternalImageURL and EnableM3UExternalAlbumArt is false", func() {
+		// (no local files — http source is gated off, reader falls through to placeholder)
+		It("skips the URL and falls through to the bundled placeholder", func() {
+			conf.Server.EnableM3UExternalAlbumArt = false
+
+			pl := putPlaylist(model.Playlist{ID: "pl-5", Name: "HttpGated", ExternalImageURL: "https://example.com/cover.jpg"})
+
+			Expect(readArtwork(pl.CoverArtID())).To(Equal(placeholderBytes()))
+		})
+	})
+
+	When("a playlist has no images and no tracks", func() {
+		// (reader falls all the way through to the bundled album placeholder)
+		It("returns the album placeholder", func() {
+			pl := putPlaylist(model.Playlist{ID: "pl-6", Name: "Empty"})
+
+			Expect(readArtwork(pl.CoverArtID())).To(Equal(placeholderBytes()))
+		})
+	})
+
+	When("a playlist has no uploaded/sidecar/external image but has tracks with album covers", func() {
+		// Library:
+		// Artist/
+		// ├── AlbumA/
+		// │   ├── 01 - Track.mp3
+		// │   └── cover.png          (real PNG — wins as tile 1 source)
+		// └── AlbumB/
+		//     ├── 01 - Track.mp3
+		//     └── cover.png          (real PNG — wins as tile 2 source)
+		// Playlist "pl-7" references tracks from both albums, so the reader
+		// generates a 2x2 tiled cover from 2 distinct album art tiles (the
+		// tiled generator mirrors when it has fewer than 4 unique tiles).
+		It("generates a tiled cover from album art", func() {
+			conf.Server.CoverArtPriority = "cover.*"
+			setLayout(fstest.MapFS{
+				"Artist/AlbumA/01 - Track.mp3": trackFile(1, "TA", map[string]any{"album": "AlbumA"}),
+				"Artist/AlbumA/cover.png":      realPNG("albumA"),
+				"Artist/AlbumB/01 - Track.mp3": trackFile(1, "TB", map[string]any{"album": "AlbumB"}),
+				"Artist/AlbumB/cover.png":      realPNG("albumB"),
+			})
+			scan()
+
+			// Pull the scanned mediafile IDs so we can attach them to the playlist.
+			mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(mfs).To(HaveLen(2))
+
+			pl := model.Playlist{ID: "pl-7", Name: "Mix", OwnerID: "admin-1"}
+			pl.AddMediaFilesByID([]string{mfs[0].ID, mfs[1].ID})
+			Expect(ds.Playlist(ctx).Put(&pl)).To(Succeed())
+
+			data := readArtwork(pl.CoverArtID())
+			// The tiled cover is a PNG-encoded 600x600 image (tileSize const).
+			// Exact bytes vary (random album order), so assert format + non-trivial size.
+			Expect(data[:8]).To(Equal([]byte{0x89, 'P', 'N', 'G', 0x0d, 0x0a, 0x1a, 0x0a}))
+			Expect(len(data)).To(BeNumerically(">", 1000))
+		})
+	})
+})
+
+func putPlaylist(pl model.Playlist) model.Playlist {
+	GinkgoHelper()
+	if pl.OwnerID == "" {
+		pl.OwnerID = "admin-1"
+	}
+	Expect(ds.Playlist(ctx).Put(&pl)).To(Succeed())
+	return pl
+}

core/artwork/e2e/radio_test.go

@@ -0,0 +1,42 @@
+package artworke2e_test
+
+import (
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Radio artwork resolution", func() {
+	BeforeEach(func() {
+		setupHarness()
+	})
+
+	When("a radio has an uploaded image", func() {
+		// <DataFolder>/
+		// └── artwork/
+		//     └── radio/
+		//         └── rd-1_logo.jpg   ← matched by UploadedImagePath()
+		It("returns the uploaded image bytes", func() {
+			writeUploadedImage(consts.EntityRadio, "rd-1_logo.jpg", imageBytes("radio-logo"))
+
+			rd := model.Radio{ID: "rd-1", Name: "Test Radio", StreamUrl: "https://example.com/stream", UploadedImage: "rd-1_logo.jpg"}
+			Expect(ds.Radio(ctx).Put(&rd)).To(Succeed())
+
+			artID := model.NewArtworkID(model.KindRadioArtwork, rd.ID, nil)
+			Expect(readArtwork(artID)).To(Equal(imageBytes("radio-logo")))
+		})
+	})
+
+	When("a radio has no uploaded image", func() {
+		// (no files on disk — reader has no sources to fall back to)
+		It("returns ErrUnavailable", func() {
+			rd := model.Radio{ID: "rd-2", Name: "Bare Radio", StreamUrl: "https://example.com/stream"}
+			Expect(ds.Radio(ctx).Put(&rd)).To(Succeed())
+
+			artID := model.NewArtworkID(model.KindRadioArtwork, rd.ID, nil)
+			_, err := readArtworkOrErr(artID)
+			Expect(err).To(HaveOccurred())
+		})
+	})
+})

core/artwork/e2e/suite_test.go

@@ -0,0 +1,106 @@
+package artworke2e_test
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+
+	_ "github.com/navidrome/navidrome/adapters/gotaglib"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/core/metrics"
+	"github.com/navidrome/navidrome/core/playlists"
+	"github.com/navidrome/navidrome/core/storage/storagetest"
+	"github.com/navidrome/navidrome/db"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/persistence"
+	"github.com/navidrome/navidrome/scanner"
+	"github.com/navidrome/navidrome/server/events"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestArtworkE2E(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Artwork E2E Suite")
+}
+
+const fakeLibScheme = "artworkfake"
+const fakeLibPath = fakeLibScheme + ":///music"
+
+var (
+	ctx    context.Context
+	ds     *tests.MockDataStore
+	aw     artwork.Artwork
+	fakeFS *storagetest.FakeFS
+)
+
+// The DB file lives in a suite-level tempdir: the go-sqlite3 singleton keeps
+// the file open for the whole suite, and Ginkgo's per-spec TempDir cleanup
+// can't unlink a file with a live handle on Windows. A suite-level tempdir
+// combined with an AfterSuite close avoids the lock conflict.
+var suiteDBTempDir string
+
+var _ = BeforeSuite(func() {
+	suiteDBTempDir = GinkgoT().TempDir()
+})
+
+var _ = AfterSuite(func() {
+	db.Close(GinkgoT().Context())
+})
+
+func setupHarness() {
+	DeferCleanup(configtest.SetupConfig())
+
+	tempDir := GinkgoT().TempDir()
+	// Reuse the suite-level DB path so the singleton connection keeps working
+	// across specs (see suiteDBTempDir comment).
+	conf.Server.DbPath = filepath.Join(suiteDBTempDir, "artwork-e2e.db") + "?_journal_mode=WAL"
+	conf.Server.DataFolder = tempDir
+	conf.Server.MusicFolder = fakeLibPath
+	conf.Server.DevExternalScanner = false
+	conf.Server.ImageCacheSize = "0" // disabled cache → reader runs on every call
+	conf.Server.EnableExternalServices = false
+
+	db.Db().SetMaxOpenConns(1)
+	ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "admin-1", UserName: "admin", IsAdmin: true})
+	db.Init(ctx)
+	DeferCleanup(func() { Expect(tests.ClearDB()).To(Succeed()) })
+
+	ds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
+
+	adminUser := model.User{ID: "admin-1", UserName: "admin", Name: "Admin", IsAdmin: true, NewPassword: "password"}
+	Expect(ds.User(ctx).Put(&adminUser)).To(Succeed())
+
+	lib := model.Library{ID: 1, Name: "Music", Path: fakeLibPath}
+	Expect(ds.Library(ctx).Put(&lib)).To(Succeed())
+	Expect(ds.User(ctx).SetUserLibraries(adminUser.ID, []int{lib.ID})).To(Succeed())
+
+	fakeFS = &storagetest.FakeFS{}
+	storagetest.Register(fakeLibScheme, fakeFS)
+
+	aw = artwork.NewArtwork(ds, artwork.GetImageCache(), newNoopFFmpeg(), &noopProvider{})
+}
+
+func scan() {
+	GinkgoHelper()
+	s := scanner.New(ctx, ds, artwork.NoopCacheWarmer(), events.NoopBroker(),
+		playlists.NewPlaylists(ds, core.NewImageUploadService()), metrics.NewNoopInstance())
+	_, err := s.ScanAll(ctx, true)
+	Expect(err).ToNot(HaveOccurred())
+}
+
+func firstAlbum() model.Album {
+	GinkgoHelper()
+	albums, err := ds.Album(ctx).GetAll(model.QueryOptions{})
+	Expect(err).ToNot(HaveOccurred())
+	Expect(albums).To(HaveLen(1), "expected exactly one album, got %d", len(albums))
+	return albums[0]
+}

core/artwork/library_fs.go

@@ -0,0 +1,44 @@
+package artwork
+
+import (
+	"context"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/core/storage"
+	"github.com/navidrome/navidrome/model"
+)
+
+// libraryView bundles the MusicFS for a library with its absolute root path,
+// so readers can open library-relative paths through FS and compose absolute
+// paths (for ffmpeg, which is path-based) via Abs.
+type libraryView struct {
+	FS      storage.MusicFS
+	absRoot string
+}
+
+// Abs returns the absolute path for a library-relative path. Returns "" for an
+// empty rel so callers (fromFFmpegTag) can treat it as "no path available".
+func (v libraryView) Abs(rel string) string {
+	if rel == "" {
+		return ""
+	}
+	return filepath.Join(v.absRoot, rel)
+}
+
+// loadLibraryView resolves the MusicFS and absolute root path in a single
+// library lookup.
+func loadLibraryView(ctx context.Context, ds model.DataStore, libID int) (libraryView, error) {
+	lib, err := ds.Library(ctx).Get(libID)
+	if err != nil {
+		return libraryView{}, err
+	}
+	s, err := storage.For(lib.Path)
+	if err != nil {
+		return libraryView{}, err
+	}
+	fs, err := s.FS()
+	if err != nil {
+		return libraryView{}, err
+	}
+	return libraryView{FS: fs, absRoot: lib.Path}, nil
+}

core/artwork/library_fs_test.go

@@ -0,0 +1,45 @@
+package artwork
+
+import (
+	"context"
+
+	"github.com/navidrome/navidrome/core/storage/storagetest"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("loadLibraryView", Ordered, func() {
+	var ctx context.Context
+	var ds *tests.MockDataStore
+
+	BeforeAll(func() {
+		storagetest.Register("fake", &storagetest.FakeFS{})
+	})
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+		ds = &tests.MockDataStore{MockedLibrary: &tests.MockLibraryRepo{}}
+	})
+
+	It("returns a view for a library backed by registered storage", func() {
+		Expect(ds.Library(ctx).Put(&model.Library{ID: 1, Path: "fake:///music"})).To(Succeed())
+
+		lib, err := loadLibraryView(ctx, ds, 1)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(lib.FS).ToNot(BeNil())
+		Expect(lib.absRoot).To(Equal("fake:///music"))
+	})
+
+	It("returns an error when the library does not exist", func() {
+		_, err := loadLibraryView(ctx, ds, 999)
+		Expect(err).To(HaveOccurred())
+	})
+
+	It("returns an error when the library path uses an unregistered scheme", func() {
+		Expect(ds.Library(ctx).Put(&model.Library{ID: 2, Path: "unsupported:///music"})).To(Succeed())
+		_, err := loadLibraryView(ctx, ds, 2)
+		Expect(err).To(HaveOccurred())
+	})
+})

core/artwork/reader_album.go

@@ -7,14 +7,13 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"path/filepath"
+	"path"
 	"slices"
 	"strings"
 	"time"
 
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/log"
@@ -24,12 +23,12 @@ import (
 
 type albumArtworkReader struct {
 	cacheKey
-	a          *artwork
-	provider   external.Provider
-	album      model.Album
-	updatedAt  *time.Time
-	imgFiles   []string
-	rootFolder string
+	a         *artwork
+	provider  external.Provider
+	album     model.Album
+	updatedAt *time.Time
+	imgFiles  []string // library-relative, forward-slash, no leading slash
+	lib       libraryView
 }
 
 func newAlbumArtworkReader(ctx context.Context, artwork *artwork, artID model.ArtworkID, provider external.Provider) (*albumArtworkReader, error) {
@@ -41,13 +40,17 @@ func newAlbumArtworkReader(ctx context.Context, artwork *artwork, artID model.Ar
 	if err != nil {
 		return nil, err
 	}
+	lib, err := loadLibraryView(ctx, artwork.ds, al.LibraryID)
+	if err != nil {
+		return nil, err
+	}
 	a := &albumArtworkReader{
-		a:          artwork,
-		provider:   provider,
-		album:      *al,
-		updatedAt:  imagesUpdateAt,
-		imgFiles:   imgFiles,
-		rootFolder: core.AbsolutePath(ctx, artwork.ds, al.LibraryID, ""),
+		a:         artwork,
+		provider:  provider,
+		album:     *al,
+		updatedAt: imagesUpdateAt,
+		imgFiles:  imgFiles,
+		lib:       lib,
 	}
 	a.cacheKey.artID = artID
 	if a.updatedAt != nil && a.updatedAt.After(al.UpdatedAt) {
@@ -61,7 +64,7 @@ func newAlbumArtworkReader(ctx context.Context, artwork *artwork, artID model.Ar
 func (a *albumArtworkReader) Key() string {
 	hashInput := conf.Server.CoverArtPriority
 	if conf.Server.EnableExternalServices {
-		hashInput += conf.Server.Agents
+		hashInput = conf.Server.Agents + hashInput
 	}
 	hash := md5.Sum([]byte(hashInput))
 	return fmt.Sprintf(
@@ -72,7 +75,7 @@ func (a *albumArtworkReader) Key() string {
 	)
 }
 func (a *albumArtworkReader) LastUpdated() time.Time {
-	return a.album.UpdatedAt
+	return a.lastUpdate
 }
 
 func (a *albumArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
@@ -86,12 +89,15 @@ func (a *albumArtworkReader) fromCoverArtPriority(ctx context.Context, ffmpeg ff
 		pattern = strings.TrimSpace(pattern)
 		switch {
 		case pattern == "embedded":
-			embedArtPath := filepath.Join(a.rootFolder, a.album.EmbedArtPath)
-			ff = append(ff, fromTag(ctx, embedArtPath), fromFFmpegTag(ctx, ffmpeg, embedArtPath))
+			embedRel := a.album.EmbedArtPath
+			ff = append(ff,
+				fromTag(ctx, a.lib.FS, embedRel),
+				fromFFmpegTag(ctx, ffmpeg, a.lib.Abs(embedRel)),
+			)
 		case pattern == "external":
 			ff = append(ff, fromAlbumExternalSource(ctx, a.album, a.provider))
 		case len(a.imgFiles) > 0:
-			ff = append(ff, fromExternalFile(ctx, a.imgFiles, pattern))
+			ff = append(ff, fromExternalFile(ctx, a.lib.FS, a.imgFiles, pattern))
 		}
 	}
 	return ff
@@ -112,19 +118,22 @@ func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...mo
 		folderIDSet[id] = true
 	}
 
-	// For multi-disc albums (2+ folders), check if all folders share a common parent
-	// that is not already included. This finds cover art in the album root folder
-	// (e.g., "Artist/Album/cover.jpg" when tracks are in "Artist/Album/CD1/" and "Artist/Album/CD2/").
-	// We skip single-folder albums to avoid pulling images from the artist folder.
+	// Check if all folders share a common parent that is not already included.
+	// This finds cover art in the album root folder (e.g., "Artist/Album/cover.jpg"
+	// when tracks are in disc subfolders like "Artist/Album/CD1/" and "Artist/Album/CD2/").
+	// For single-folder albums, the parent is only included when the folder has no
+	// images of its own (indicating a disc subfolder needing parent artwork).
 	if commonParentID := commonParentFolder(folders, folderIDSet); commonParentID != "" {
-		parentFolder, err := ds.Folder(ctx).Get(commonParentID)
-		if errors.Is(err, model.ErrNotFound) {
-			log.Warn(ctx, "Parent folder not found for album cover art lookup", "parentID", commonParentID)
-		} else if err != nil {
-			return nil, nil, nil, err
-		}
-		if parentFolder != nil {
-			folders = append(folders, *parentFolder)
+		if len(folders) >= 2 || !anyFolderHasImages(folders) {
+			parentFolder, err := ds.Folder(ctx).Get(commonParentID)
+			if errors.Is(err, model.ErrNotFound) {
+				log.Warn(ctx, "Parent folder not found for album cover art lookup", "parentID", commonParentID)
+			} else if err != nil {
+				return nil, nil, nil, err
+			}
+			if parentFolder != nil && parentFolder.Path != "." {
+				folders = append(folders, *parentFolder)
+			}
 		}
 	}
 
@@ -132,13 +141,13 @@ func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...mo
 	var imgFiles []string
 	var updatedAt time.Time
 	for _, f := range folders {
-		path := f.AbsolutePath()
-		paths = append(paths, path)
+		paths = append(paths, f.AbsolutePath())
 		if f.ImagesUpdatedAt.After(updatedAt) {
 			updatedAt = f.ImagesUpdatedAt
 		}
+		rel := strings.TrimPrefix(path.Join(f.Path, f.Name), "/")
 		for _, img := range f.ImageFiles {
-			imgFiles = append(imgFiles, filepath.Join(path, img))
+			imgFiles = append(imgFiles, path.Join(rel, img))
 		}
 	}
 
@@ -150,10 +159,19 @@ func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...mo
 	return paths, imgFiles, &updatedAt, nil
 }
 
+func anyFolderHasImages(folders []model.Folder) bool {
+	for _, f := range folders {
+		if len(f.ImageFiles) > 0 {
+			return true
+		}
+	}
+	return false
+}
+
 // commonParentFolder returns the shared parent folder ID when all folders have the
 // same parent and that parent is not already in folderIDSet. Returns "" otherwise.
 func commonParentFolder(folders []model.Folder, folderIDSet map[string]bool) string {
-	if len(folders) < 2 {
+	if len(folders) == 0 {
 		return ""
 	}
 	parentID := folders[0].ParentID
@@ -168,23 +186,21 @@ func commonParentFolder(folders []model.Folder, folderIDSet map[string]bool) str
 	return parentID
 }
 
-// compareImageFiles compares two image file paths for sorting.
-// It extracts the base filename (without extension) and compares case-insensitively.
-// This ensures that "cover.jpg" sorts before "cover.1.jpg" since "cover" < "cover.1".
-// Note: This function is called O(n log n) times during sorting, but in practice albums
-// typically have only 1-20 image files, making the repeated string operations negligible.
+// compareImageFiles sorts image paths by: base filename (natural order),
+// then path depth (shallower first), then full path (stable tiebreaker).
 func compareImageFiles(a, b string) int {
 	// Case-insensitive comparison
 	a = strings.ToLower(a)
 	b = strings.ToLower(b)
 
 	// Extract base filenames without extensions
-	baseA := strings.TrimSuffix(filepath.Base(a), filepath.Ext(a))
-	baseB := strings.TrimSuffix(filepath.Base(b), filepath.Ext(b))
+	baseA := strings.TrimSuffix(path.Base(a), path.Ext(a))
+	baseB := strings.TrimSuffix(path.Base(b), path.Ext(b))
 
-	// Compare base names first, then full paths if equal
+	// Compare base names first, then prefer shallower paths, then full path as tiebreaker
 	return cmp.Or(
 		natural.Compare(baseA, baseB),
+		cmp.Compare(strings.Count(a, "/"), strings.Count(b, "/")),
 		natural.Compare(a, b),
 	)
 }

core/artwork/reader_album_test.go

@@ -3,7 +3,6 @@ package artwork
 import (
 	"context"
 	"errors"
-	"path/filepath"
 	"time"
 
 	"github.com/navidrome/navidrome/model"
@@ -69,11 +68,11 @@ var _ = Describe("Album Artwork Reader", func() {
 			// Files should be sorted by base filename without extension, then by full path
 			// "back" < "cover", so back.jpg comes first
 			// Then all cover.jpg files, sorted by path
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/Disc1/back.jpg")))
-			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/Disc1/cover.jpg")))
-			Expect(imgFiles[2]).To(Equal(filepath.FromSlash("Artist/Album/Disc2/cover.jpg")))
-			Expect(imgFiles[3]).To(Equal(filepath.FromSlash("Artist/Album/Disc10/cover.jpg")))
-			Expect(imgFiles[4]).To(Equal(filepath.FromSlash("Artist/Album/Disc1/cover.1.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/Disc1/back.jpg"))
+			Expect(imgFiles[1]).To(Equal("Artist/Album/Disc1/cover.jpg"))
+			Expect(imgFiles[2]).To(Equal("Artist/Album/Disc2/cover.jpg"))
+			Expect(imgFiles[3]).To(Equal("Artist/Album/Disc10/cover.jpg"))
+			Expect(imgFiles[4]).To(Equal("Artist/Album/Disc1/cover.1.jpg"))
 		})
 
 		It("prioritizes files without numeric suffixes", func() {
@@ -92,9 +91,9 @@ var _ = Describe("Album Artwork Reader", func() {
 			Expect(imgFiles).To(HaveLen(3))
 
 			// cover.jpg should come first because "cover" < "cover.1" < "cover.2"
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
-			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/cover.1.jpg")))
-			Expect(imgFiles[2]).To(Equal(filepath.FromSlash("Artist/Album/cover.2.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/cover.jpg"))
+			Expect(imgFiles[1]).To(Equal("Artist/Album/cover.1.jpg"))
+			Expect(imgFiles[2]).To(Equal("Artist/Album/cover.2.jpg"))
 		})
 
 		It("handles case-insensitive sorting", func() {
@@ -113,9 +112,9 @@ var _ = Describe("Album Artwork Reader", func() {
 			Expect(imgFiles).To(HaveLen(3))
 
 			// Files should be sorted case-insensitively: BACK, cover, Folder
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/BACK.jpg")))
-			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
-			Expect(imgFiles[2]).To(Equal(filepath.FromSlash("Artist/Album/Folder.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/BACK.jpg"))
+			Expect(imgFiles[1]).To(Equal("Artist/Album/cover.jpg"))
+			Expect(imgFiles[2]).To(Equal("Artist/Album/Folder.jpg"))
 		})
 
 		It("includes images from parent folder for multi-disc albums", func() {
@@ -151,8 +150,8 @@ var _ = Describe("Album Artwork Reader", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(*imagesUpdatedAt).To(Equal(expectedAt))
 			Expect(imgFiles).To(HaveLen(2))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/back.jpg")))
-			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/back.jpg"))
+			Expect(imgFiles[1]).To(Equal("Artist/Album/cover.jpg"))
 		})
 
 		It("does not query parent when parent ID is already in album folders", func() {
@@ -179,7 +178,7 @@ var _ = Describe("Album Artwork Reader", func() {
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(imgFiles).To(HaveLen(1))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/cover.jpg"))
 			// Get should not have been called (parent already in folder set)
 			Expect(repo.getCallCount).To(Equal(0))
 		})
@@ -209,14 +208,47 @@ var _ = Describe("Album Artwork Reader", func() {
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(imgFiles).To(HaveLen(1))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist1/Album/part1/cover.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist1/Album/part1/cover.jpg"))
 			// Get should not have been called (different parents)
 			Expect(repo.getCallCount).To(Equal(0))
 		})
 
-		It("does not query parent for single-folder albums", func() {
-			// A single-folder album's parent is typically the artist folder,
-			// which should not be searched for cover art
+		It("does not include top-level parent for multi-folder albums", func() {
+			// Two album parts under the same artist folder — parent is artist-level
+			repo.result = []model.Folder{
+				{
+					ID:              "folder1",
+					Path:            ".",
+					Name:            "AlbumPart1",
+					ParentID:        "artistFolder",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{"cover.jpg"},
+				},
+				{
+					ID:              "folder2",
+					Path:            ".",
+					Name:            "AlbumPart2",
+					ParentID:        "artistFolder",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{},
+				},
+			}
+			repo.parentResult = &model.Folder{
+				ID:         "artistFolder",
+				Path:       ".",
+				Name:       "Artist",
+				ImageFiles: []string{"artist.jpg"},
+			}
+
+			_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(imgFiles).To(HaveLen(1))
+			Expect(imgFiles[0]).To(Equal("AlbumPart1/cover.jpg"))
+			Expect(repo.getCallCount).To(Equal(1))
+		})
+
+		It("does not query parent for single-folder albums that already have images", func() {
 			repo.result = []model.Folder{
 				{
 					ID:              "folder1",
@@ -232,11 +264,38 @@ var _ = Describe("Album Artwork Reader", func() {
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(imgFiles).To(HaveLen(1))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
-			// Get should not have been called (single folder, no parent lookup)
+			Expect(imgFiles[0]).To(Equal("Artist/Album/cover.jpg"))
 			Expect(repo.getCallCount).To(Equal(0))
 		})
 
+		It("includes parent images for single-disc-subfolder albums", func() {
+			repo.result = []model.Folder{
+				{
+					ID:              "folder1",
+					Path:            "Artist/Album",
+					Name:            "disc1",
+					ParentID:        "albumFolder",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{},
+				},
+			}
+			repo.parentResult = &model.Folder{
+				ID:              "albumFolder",
+				Path:            "Artist",
+				Name:            "Album",
+				ImagesUpdatedAt: expectedAt,
+				ImageFiles:      []string{"cover.jpg"},
+			}
+
+			_, imgFiles, imagesUpdatedAt, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(*imagesUpdatedAt).To(Equal(expectedAt))
+			Expect(imgFiles).To(HaveLen(1))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/cover.jpg"))
+			Expect(repo.getCallCount).To(Equal(1))
+		})
+
 		It("propagates non-ErrNotFound errors from parent folder lookup", func() {
 			repo.result = []model.Folder{
 				{
@@ -290,7 +349,7 @@ var _ = Describe("Album Artwork Reader", func() {
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(imgFiles).To(HaveLen(1))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/CD1/cover.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/CD1/cover.jpg"))
 			Expect(repo.getCallCount).To(Equal(1))
 		})
 	})

core/artwork/reader_artist.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"io/fs"
 	"os"
+	"path"
 	"path/filepath"
 	"slices"
 	"strings"
@@ -35,6 +36,7 @@ type artistReader struct {
 	artistFolder     string
 	imgFiles         []string
 	imgFolderImgPath string // cached path from ArtistImageFolder lookup
+	lib              libraryView
 }
 
 func newArtistArtworkReader(ctx context.Context, artwork *artwork, artID model.ArtworkID, provider external.Provider) (*artistReader, error) {
@@ -60,12 +62,20 @@ func newArtistArtworkReader(ctx context.Context, artwork *artwork, artID model.A
 	if err != nil {
 		return nil, err
 	}
+	var lib libraryView
+	if len(als) > 0 {
+		lib, err = loadLibraryView(ctx, artwork.ds, als[0].LibraryID)
+		if err != nil {
+			return nil, err
+		}
+	}
 	a := &artistReader{
 		a:            artwork,
 		provider:     provider,
 		artist:       *ar,
 		artistFolder: artistFolder,
 		imgFiles:     imgFiles,
+		lib:          lib,
 	}
 	// TODO Find a way to factor in the ExternalUpdateInfoAt in the cache key. Problem is that it can
 	// change _after_ retrieving from external sources, making the key invalid
@@ -124,38 +134,62 @@ func (a *artistReader) fromArtistArtPriority(ctx context.Context, priority strin
 		case pattern == "image-folder":
 			ff = append(ff, a.fromArtistImageFolder(ctx))
 		case strings.HasPrefix(pattern, "album/"):
-			ff = append(ff, fromExternalFile(ctx, a.imgFiles, strings.TrimPrefix(pattern, "album/")))
+			if a.lib.FS != nil {
+				ff = append(ff, fromExternalFile(ctx, a.lib.FS, a.imgFiles, strings.TrimPrefix(pattern, "album/")))
+			}
 		default:
-			ff = append(ff, fromArtistFolder(ctx, a.artistFolder, pattern))
+			ff = append(ff, fromArtistFolder(ctx, a.lib.FS, a.lib.absRoot, a.artistFolder, pattern))
 		}
 	}
 	return ff
 }
 
-func fromArtistFolder(ctx context.Context, artistFolder string, pattern string) sourceFunc {
+// fromArtistFolder walks up from artistFolder toward libPath looking for a
+// file matching pattern. Traversal is bounded by both maxArtistFolderTraversalDepth
+// and the library root: once we reach libPath (or if artistFolder is outside
+// libPath), the walk stops. All reads go through libFS, which keeps artwork
+// resolution scoped to the configured library.
+func fromArtistFolder(ctx context.Context, libFS fs.FS, libPath, artistFolder, pattern string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
+		if libFS == nil {
+			return nil, "", fmt.Errorf("artist folder lookup unavailable")
+		}
+		rel, err := filepath.Rel(libPath, artistFolder)
+		if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+			return nil, "", fmt.Errorf(`artist folder '%s' is outside library '%s'`, artistFolder, libPath)
+		}
+		// fs.Glob / path.Join below expect forward-slash paths; filepath.Rel may
+		// return backslash separators on Windows.
+		rel = filepath.ToSlash(rel)
 		current := artistFolder
 		for range maxArtistFolderTraversalDepth {
-			if reader, path, err := findImageInFolder(ctx, current, pattern); err == nil {
-				return reader, path, nil
+			reader, hit, err := findImageInFolder(ctx, libFS, rel, current, pattern)
+			if err == nil {
+				return reader, hit, nil
 			}
-
-			parent := filepath.Dir(current)
-			if parent == current {
-				break
+			if rel == "." {
+				break // reached library root; don't traverse above it
 			}
-			current = parent
+			rel = path.Dir(rel)
+			current = filepath.Dir(current)
 		}
-		return nil, "", fmt.Errorf(`no matches for '%s' in '%s' or its parent directories`, pattern, artistFolder)
+		return nil, "", fmt.Errorf(`no matches for '%s' in '%s' or its parent directories (within library)`, pattern, artistFolder)
 	}
 }
 
-func findImageInFolder(ctx context.Context, folder, pattern string) (io.ReadCloser, string, error) {
-	log.Trace(ctx, "looking for artist image", "pattern", pattern, "folder", folder)
-	fsys := os.DirFS(folder)
-	matches, err := fs.Glob(fsys, pattern)
+// findImageInFolder globs libFS at relFolder for pattern and returns the first
+// matching image. absFolder is used only for the returned display path and log
+// messages so callers see absolute-looking paths consistent with the rest of
+// the artwork pipeline.
+func findImageInFolder(ctx context.Context, libFS fs.FS, relFolder, absFolder, pattern string) (io.ReadCloser, string, error) {
+	log.Trace(ctx, "looking for artist image", "pattern", pattern, "folder", absFolder)
+	globPattern := pattern
+	if relFolder != "." {
+		globPattern = path.Join(escapeGlobLiteral(relFolder), pattern)
+	}
+	matches, err := fs.Glob(libFS, globPattern)
 	if err != nil {
-		log.Warn(ctx, "Error matching artist image pattern", "pattern", pattern, "folder", folder, err)
+		log.Warn(ctx, "Error matching artist image pattern", "pattern", pattern, "folder", absFolder, err)
 		return nil, "", err
 	}
 
@@ -172,18 +206,30 @@ func findImageInFolder(ctx context.Context, folder, pattern string) (io.ReadClos
 	// suffixes (e.g., artist.jpg before artist.1.jpg)
 	slices.SortFunc(imagePaths, compareImageFiles)
 
-	// Try to open files in sorted order
 	for _, p := range imagePaths {
-		filePath := filepath.Join(folder, p)
-		f, err := os.Open(filePath)
+		f, err := libFS.Open(p)
 		if err != nil {
-			log.Warn(ctx, "Could not open cover art file", "file", filePath, err)
+			log.Warn(ctx, "Could not open cover art file", "file", p, err)
 			continue
 		}
-		return f, filePath, nil
+		_, name := path.Split(p)
+		return f, filepath.Join(absFolder, name), nil
 	}
 
-	return nil, "", fmt.Errorf(`no matches for '%s' in '%s'`, pattern, folder)
+	return nil, "", fmt.Errorf(`no matches for '%s' in '%s'`, pattern, absFolder)
+}
+
+func escapeGlobLiteral(s string) string {
+	var b strings.Builder
+	b.Grow(len(s))
+	for _, r := range s {
+		switch r {
+		case '\\', '*', '?', '[', ']':
+			b.WriteByte('\\')
+		}
+		b.WriteRune(r)
+	}
+	return b.String()
 }
 
 func loadArtistFolder(ctx context.Context, ds model.DataStore, albums model.Albums, paths []string) (string, time.Time, error) {

core/artwork/reader_artist_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"time"
@@ -66,7 +67,7 @@ var _ = Describe("artistArtworkReader", func() {
 				}
 				folder, upd, err := loadArtistFolder(ctx, fds, albums, paths)
 				Expect(err).ToNot(HaveOccurred())
-				Expect(folder).To(Equal("/music/artist"))
+				Expect(folder).To(Equal(filepath.FromSlash("/music/artist")))
 				Expect(upd).To(Equal(expectedUpdTime))
 			})
 		})
@@ -92,7 +93,7 @@ var _ = Describe("artistArtworkReader", func() {
 				}
 				folder, upd, err := loadArtistFolder(ctx, fds, albums, paths)
 				Expect(err).ToNot(HaveOccurred())
-				Expect(folder).To(Equal("/music/artist"))
+				Expect(folder).To(Equal(filepath.FromSlash("/music/artist")))
 				Expect(upd).To(Equal(expectedUpdTime))
 			})
 		})
@@ -117,12 +118,14 @@ var _ = Describe("artistArtworkReader", func() {
 		var (
 			ctx      context.Context
 			tempDir  string
+			libFS    fs.FS
 			testFunc sourceFunc
 		)
 
 		BeforeEach(func() {
 			ctx = context.Background()
 			tempDir = GinkgoT().TempDir()
+			libFS = os.DirFS(tempDir)
 		})
 
 		When("artist folder contains matching image", func() {
@@ -134,7 +137,7 @@ var _ = Describe("artistArtworkReader", func() {
 				artistImagePath := filepath.Join(artistDir, "artist.jpg")
 				Expect(os.WriteFile(artistImagePath, []byte("fake image data"), 0600)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("finds and returns the image", func() {
@@ -151,6 +154,30 @@ var _ = Describe("artistArtworkReader", func() {
 			})
 		})
 
+		When("artist folder name contains glob metacharacters", func() {
+			BeforeEach(func() {
+				artistDir := filepath.Join(tempDir, "Artist [Live]")
+				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
+
+				artistImagePath := filepath.Join(artistDir, "artist.jpg")
+				Expect(os.WriteFile(artistImagePath, []byte("bracketed artist image"), 0600)).To(Succeed())
+
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
+			})
+
+			It("treats the folder path literally when globbing through the library fs", func() {
+				reader, path, err := testFunc()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(reader).ToNot(BeNil())
+				Expect(path).To(ContainSubstring("Artist [Live]" + string(filepath.Separator) + "artist.jpg"))
+
+				data, err := io.ReadAll(reader)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(string(data)).To(Equal("bracketed artist image"))
+				reader.Close()
+			})
+		})
+
 		When("artist folder is empty but parent contains image", func() {
 			BeforeEach(func() {
 				// Create test structure: /temp/parent/artist.jpg and /temp/parent/artist/album/
@@ -163,7 +190,7 @@ var _ = Describe("artistArtworkReader", func() {
 				artistImagePath := filepath.Join(parentDir, "artist.jpg")
 				Expect(os.WriteFile(artistImagePath, []byte("parent image"), 0600)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("finds image in parent directory", func() {
@@ -191,7 +218,7 @@ var _ = Describe("artistArtworkReader", func() {
 				artistImagePath := filepath.Join(grandparentDir, "artist.jpg")
 				Expect(os.WriteFile(artistImagePath, []byte("grandparent image"), 0600)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("finds image in grandparent directory", func() {
@@ -220,7 +247,7 @@ var _ = Describe("artistArtworkReader", func() {
 				Expect(os.WriteFile(filepath.Join(parentDir, "artist.jpg"), []byte("parent level"), 0600)).To(Succeed())
 				Expect(os.WriteFile(filepath.Join(grandparentDir, "artist.jpg"), []byte("grandparent level"), 0600)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("prioritizes the closest (artist folder) image", func() {
@@ -246,7 +273,7 @@ var _ = Describe("artistArtworkReader", func() {
 				Expect(os.WriteFile(filepath.Join(artistDir, "artist.png"), []byte("png image"), 0600)).To(Succeed())
 				Expect(os.WriteFile(filepath.Join(artistDir, "artist.jpg"), []byte("jpg image"), 0600)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("returns the first valid image file in sorted order", func() {
@@ -273,7 +300,7 @@ var _ = Describe("artistArtworkReader", func() {
 				Expect(os.WriteFile(filepath.Join(artistDir, "artist.jpg"), []byte("artist main"), 0600)).To(Succeed())
 				Expect(os.WriteFile(filepath.Join(artistDir, "artist.2.jpg"), []byte("artist 2"), 0600)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("returns artist.jpg before artist.1.jpg and artist.2.jpg", func() {
@@ -301,7 +328,7 @@ var _ = Describe("artistArtworkReader", func() {
 				Expect(os.WriteFile(filepath.Join(artistDir, "artist.jpg"), []byte("artist"), 0600)).To(Succeed())
 				Expect(os.WriteFile(filepath.Join(artistDir, "BACK.jpg"), []byte("back"), 0600)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "*.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "*.*")
 			})
 
 			It("sorts case-insensitively", func() {
@@ -327,7 +354,7 @@ var _ = Describe("artistArtworkReader", func() {
 				// Create non-matching files
 				Expect(os.WriteFile(filepath.Join(artistDir, "cover.jpg"), []byte("cover image"), 0600)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("returns an error", func() {
@@ -346,7 +373,7 @@ var _ = Describe("artistArtworkReader", func() {
 				artistDir := filepath.Join(tempDir, "artist")
 				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("handles root boundary gracefully", func() {
@@ -367,7 +394,7 @@ var _ = Describe("artistArtworkReader", func() {
 				restrictedFile := filepath.Join(artistDir, "artist.jpg")
 				Expect(os.WriteFile(restrictedFile, []byte("restricted"), 0600)).To(Succeed())
 
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("logs warning and continues searching", func() {
@@ -397,7 +424,7 @@ var _ = Describe("artistArtworkReader", func() {
 				Expect(os.WriteFile(artistImagePath, []byte("single album artist image"), 0600)).To(Succeed())
 
 				// The fromArtistFolder is called with the artist folder path
-				testFunc = fromArtistFolder(ctx, artistDir, "artist.*")
+				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
 			})
 
 			It("finds artist.jpg in artist folder for single album artist", func() {

core/artwork/reader_disc.go

@@ -5,7 +5,7 @@ import (
 	"crypto/md5"
 	"fmt"
 	"io"
-	"os"
+	"path"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -13,7 +13,6 @@ import (
 
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -24,10 +23,11 @@ type discArtworkReader struct {
 	a              *artwork
 	album          model.Album
 	discNumber     int
-	imgFiles       []string
-	discFolders    map[string]bool
+	imgFiles       []string        // library-relative, forward-slash, no leading slash
+	discFoldersRel map[string]bool // library-relative folder paths
 	isMultiFolder  bool
-	firstTrackPath string
+	firstTrackRel  string // library-relative; for fromTag / ffmpeg via lib.Abs
+	lib            libraryView
 	updatedAt      *time.Time
 }
 
@@ -57,18 +57,23 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 		return nil, err
 	}
 
-	// Build disc folder set and find first track
-	discFolders := make(map[string]bool)
-	var firstTrackPath string
+	lib, err := loadLibraryView(ctx, a.ds, al.LibraryID)
+	if err != nil {
+		return nil, err
+	}
+
+	// Build disc folder set and find first track. mf.Path is already library-relative.
+	var firstTrackRel string
 	allFolderIDs := make(map[string]bool)
 	for _, mf := range mfs {
 		allFolderIDs[mf.FolderID] = true
-		if firstTrackPath == "" {
-			firstTrackPath = mf.Path
+		if firstTrackRel == "" {
+			firstTrackRel = filepath.ToSlash(mf.Path)
 		}
 	}
 
-	// Resolve folder IDs to absolute paths
+	// Resolve folder IDs to library-relative paths
+	discFoldersRel := make(map[string]bool)
 	if len(allFolderIDs) > 0 {
 		folderIDs := make([]string, 0, len(allFolderIDs))
 		for id := range allFolderIDs {
@@ -81,7 +86,8 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 			return nil, err
 		}
 		for _, f := range folders {
-			discFolders[f.AbsolutePath()] = true
+			rel := strings.TrimPrefix(path.Join(f.Path, f.Name), "/")
+			discFoldersRel[rel] = true
 		}
 	}
 
@@ -92,9 +98,10 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 		album:          *al,
 		discNumber:     discNumber,
 		imgFiles:       imgFiles,
-		discFolders:    discFolders,
+		discFoldersRel: discFoldersRel,
 		isMultiFolder:  isMultiFolder,
-		firstTrackPath: core.AbsolutePath(ctx, a.ds, al.LibraryID, firstTrackPath),
+		firstTrackRel:  firstTrackRel,
+		lib:            lib,
 		updatedAt:      imagesUpdatedAt,
 	}
 	r.cacheKey.artID = artID
@@ -116,7 +123,7 @@ func (d *discArtworkReader) Key() string {
 }
 
 func (d *discArtworkReader) LastUpdated() time.Time {
-	return d.album.UpdatedAt
+	return d.lastUpdate
 }
 
 func (d *discArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
@@ -133,7 +140,10 @@ func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmp
 		pattern = strings.TrimSpace(pattern)
 		switch {
 		case pattern == "embedded":
-			ff = append(ff, fromTag(ctx, d.firstTrackPath), fromFFmpegTag(ctx, ffmpeg, d.firstTrackPath))
+			ff = append(ff,
+				fromTag(ctx, d.lib.FS, d.firstTrackRel),
+				fromFFmpegTag(ctx, ffmpeg, d.lib.Abs(d.firstTrackRel)),
+			)
 		case pattern == "external":
 			// Not supported for disc art, silently ignore
 		case pattern == "discsubtitle":
@@ -152,12 +162,12 @@ func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmp
 func (d *discArtworkReader) fromDiscSubtitle(ctx context.Context, subtitle string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
 		for _, file := range d.imgFiles {
-			_, name := filepath.Split(file)
-			stem := strings.TrimSuffix(name, filepath.Ext(name))
+			name := path.Base(file)
+			stem := strings.TrimSuffix(name, path.Ext(name))
 			if !strings.EqualFold(stem, subtitle) {
 				continue
 			}
-			f, err := os.Open(file)
+			f, err := d.lib.FS.Open(file)
 			if err != nil {
 				log.Warn(ctx, "Could not open disc art file", "file", file, err)
 				continue
@@ -168,47 +178,38 @@ func (d *discArtworkReader) fromDiscSubtitle(ctx context.Context, subtitle strin
 	}
 }
 
-// extractDiscNumber extracts a disc number from a filename based on a glob pattern.
-// It finds the portion of the filename that the wildcard matched and parses leading
-// digits as the disc number. Returns (0, false) if the pattern doesn't match or
-// no leading digits are found in the wildcard portion.
+// globMetaChars holds the substitution metacharacters understood by
+// filepath.Match. The '\' escape character is intentionally excluded:
+// disc art patterns come from user config and never include escaped
+// metachars in practice, and treating '\' as a metachar would misalign
+// the literal-prefix extraction in extractDiscNumber.
+const globMetaChars = "*?["
+
+// extractDiscNumber parses the disc number from a filename matched by a
+// filepath.Match-style glob pattern.
+//
+// Both pattern and filename must already be lowercased by the caller, which
+// is also expected to have verified that filepath.Match(pattern, filename)
+// is true before calling this function.
 func extractDiscNumber(pattern, filename string) (int, bool) {
-	filename = strings.ToLower(filename)
-	pattern = strings.ToLower(pattern)
-
-	matched, err := filepath.Match(pattern, filename)
-	if err != nil || !matched {
+	metaIdx := strings.IndexAny(pattern, globMetaChars)
+	if metaIdx < 0 {
 		return 0, false
 	}
-
-	// Find the prefix before the first '*' in the pattern
-	starIdx := strings.IndexByte(pattern, '*')
-	if starIdx < 0 {
-		return 0, false
-	}
-	prefix := pattern[:starIdx]
-
-	// Strip the prefix from the filename to get the wildcard-matched portion
+	prefix := pattern[:metaIdx]
 	if !strings.HasPrefix(filename, prefix) {
 		return 0, false
 	}
-	remainder := filename[len(prefix):]
 
-	// Extract leading ASCII digits from the remainder
-	var digits []byte
-	for _, r := range remainder {
-		if r >= '0' && r <= '9' {
-			digits = append(digits, byte(r))
-		} else {
-			break
-		}
+	start := len(prefix)
+	end := start
+	for end < len(filename) && filename[end] >= '0' && filename[end] <= '9' {
+		end++
 	}
-
-	if len(digits) == 0 {
+	if end == start {
 		return 0, false
 	}
-
-	num, err := strconv.Atoi(string(digits))
+	num, err := strconv.Atoi(filename[start:end])
 	if err != nil {
 		return 0, false
 	}
@@ -216,20 +217,15 @@ func extractDiscNumber(pattern, filename string) (int, bool) {
 }
 
 // fromExternalFile returns a sourceFunc that matches image files against a glob
-// pattern with disc-number-aware filtering.
-//
-// Matching rules:
-//   - If a disc number can be extracted from the filename, the file matches only if
-//     the number equals the target disc number.
-//   - If no number is found and this is a multi-folder album, the file matches if
-//     it's in a folder containing tracks for this disc.
-//   - If no number is found and this is a single-folder album, the file is skipped
-//     (ambiguous).
+// pattern. A numbered filename whose number equals the target disc wins over
+// any unnumbered candidate; callers must pass a lowercase pattern.
 func (d *discArtworkReader) fromExternalFile(ctx context.Context, pattern string) sourceFunc {
+	isLiteral := !strings.ContainsAny(pattern, globMetaChars)
 	return func() (io.ReadCloser, string, error) {
+		var fallbacks []string
 		for _, file := range d.imgFiles {
-			_, name := filepath.Split(file)
-			match, err := filepath.Match(pattern, strings.ToLower(name))
+			name := strings.ToLower(path.Base(file))
+			match, err := filepath.Match(pattern, name)
 			if err != nil {
 				log.Warn(ctx, "Error matching disc art file to pattern", "pattern", pattern, "file", file)
 				continue
@@ -238,25 +234,28 @@ func (d *discArtworkReader) fromExternalFile(ctx context.Context, pattern string
 				continue
 			}
 
-			// Try to extract disc number from filename
-			num, hasNum := extractDiscNumber(pattern, name)
-			if hasNum {
-				// File has a disc number — must match target disc
-				if num != d.discNumber {
-					continue
+			if !isLiteral {
+				if num, hasNum := extractDiscNumber(pattern, name); hasNum {
+					if num != d.discNumber {
+						continue
+					}
+					f, err := d.lib.FS.Open(file)
+					if err != nil {
+						log.Warn(ctx, "Could not open disc art file", "file", file, err)
+						continue
+					}
+					return f, file, nil
 				}
-			} else if d.isMultiFolder {
-				// No number, multi-folder: match by folder association
-				dir := filepath.Dir(file)
-				if !d.discFolders[dir] {
-					continue
-				}
-			} else {
-				// No number, single-folder: ambiguous, skip
-				continue
 			}
 
-			f, err := os.Open(file)
+			if d.isMultiFolder && !d.discFoldersRel[path.Dir(file)] {
+				continue
+			}
+			fallbacks = append(fallbacks, file)
+		}
+
+		for _, file := range fallbacks {
+			f, err := d.lib.FS.Open(file)
 			if err != nil {
 				log.Warn(ctx, "Could not open disc art file", "file", file, err)
 				continue

core/artwork/reader_disc_test.go

@@ -42,11 +42,24 @@ var _ = Describe("Disc Artwork Reader", func() {
 			// Case insensitive (filename already lowered by caller)
 			Entry("Disc1.jpg lowered", "disc*.*", "disc1.jpg", 1, true),
 
-			// Pattern doesn't match
-			Entry("cover.jpg doesn't match disc*.*", "disc*.*", "cover.jpg", 0, false),
+			// HasPrefix guard: filename doesn't share the pattern's literal prefix
+			Entry("cover.jpg with disc*.* (no prefix match)", "disc*.*", "cover.jpg", 0, false),
 
 			// Pattern with no wildcard before dot
 			Entry("front1.jpg with front*.*", "front*.*", "front1.jpg", 1, true),
+
+			// '?' single-char wildcard
+			Entry("disc?.jpg with disc1.jpg", "disc?.jpg", "disc1.jpg", 1, true),
+			Entry("disc?.jpg with disc2.jpg", "disc?.jpg", "disc2.jpg", 2, true),
+			Entry("cd??.jpg with cd07.jpg", "cd??.jpg", "cd07.jpg", 7, true),
+
+			// '[...]' character class wildcard
+			Entry("cd[12].jpg with cd1.jpg", "cd[12].jpg", "cd1.jpg", 1, true),
+			Entry("cd[12].jpg with cd2.jpg", "cd[12].jpg", "cd2.jpg", 2, true),
+			Entry("disc[0-9].jpg with disc5.jpg", "disc[0-9].jpg", "disc5.jpg", 5, true),
+
+			// Literal pattern (no wildcard) returns false
+			Entry("shellac.png literal", "shellac.png", "shellac.png", 0, false),
 		)
 	})
 
@@ -61,20 +74,27 @@ var _ = Describe("Disc Artwork Reader", func() {
 			tmpDir = GinkgoT().TempDir()
 		})
 
-		createFile := func(path string) string {
-			fullPath := filepath.Join(tmpDir, filepath.FromSlash(path))
+		// createFile creates the file on disk and returns its library-relative forward-slash path.
+		createFile := func(relPath string) string {
+			fullPath := filepath.Join(tmpDir, filepath.FromSlash(relPath))
 			Expect(os.MkdirAll(filepath.Dir(fullPath), 0755)).To(Succeed())
 			Expect(os.WriteFile(fullPath, []byte("image data"), 0600)).To(Succeed())
-			return fullPath
+			return relPath
+		}
+
+		// removeFile removes a library-relative file from disk.
+		removeFile := func(relPath string) {
+			Expect(os.Remove(filepath.Join(tmpDir, filepath.FromSlash(relPath)))).To(Succeed())
 		}
 
 		It("matches file with disc number in single-folder album", func() {
 			f1 := createFile("album/disc1.jpg")
 			f2 := createFile("album/disc2.jpg")
 			reader := &discArtworkReader{
-				discNumber:  1,
-				imgFiles:    []string{f1, f2},
-				discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+				discNumber:     1,
+				imgFiles:       []string{f1, f2},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -85,27 +105,203 @@ var _ = Describe("Disc Artwork Reader", func() {
 			Expect(path).To(Equal(f1))
 		})
 
-		It("skips file without number in single-folder album", func() {
-			f1 := createFile("album/disc.jpg")
+		It("matches file without number in single-folder album (shared disc art)", func() {
+			f1 := createFile("album/cover.png")
 			reader := &discArtworkReader{
-				discNumber:  1,
-				imgFiles:    []string{f1},
-				discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+				discNumber:     1,
+				imgFiles:       []string{f1},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+			}
+
+			sf := reader.fromExternalFile(ctx, "cover.*")
+			r, path, err := sf()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(r).ToNot(BeNil())
+			r.Close()
+			Expect(path).To(Equal(f1))
+		})
+
+		It("returns shared disc art for every disc number in single-folder album", func() {
+			f1 := createFile("album/shellac.png")
+			makeReader := func(discNum int) *discArtworkReader {
+				return &discArtworkReader{
+					discNumber:     discNum,
+					imgFiles:       []string{f1},
+					discFoldersRel: map[string]bool{"album": true},
+					lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+				}
+			}
+
+			for _, disc := range []int{1, 2, 5} {
+				sf := makeReader(disc).fromExternalFile(ctx, "shellac.png")
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred(), "disc %d", disc)
+				Expect(r).ToNot(BeNil())
+				r.Close()
+				Expect(path).To(Equal(f1), "disc %d", disc)
+			}
+		})
+
+		It("numbered and unnumbered patterns both resolve against the same reader", func() {
+			f1 := createFile("album/cover.png")
+			f2 := createFile("album/disc1.jpg")
+			f3 := createFile("album/disc2.jpg")
+			reader := &discArtworkReader{
+				discNumber:     2,
+				imgFiles:       []string{f1, f2, f3},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
-			r, _, _ := sf()
-			Expect(r).To(BeNil())
+			r, path, err := sf()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(r).ToNot(BeNil())
+			r.Close()
+			Expect(path).To(Equal(f3))
+
+			sf = reader.fromExternalFile(ctx, "cover.*")
+			r, path, err = sf()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(r).ToNot(BeNil())
+			r.Close()
+			Expect(path).To(Equal(f1))
 		})
 
+		It("respects DiscArtPriority order when both numbered and unnumbered patterns match", func() {
+			f1 := createFile("album/cover.png")
+			f2 := createFile("album/disc1.jpg")
+			reader := &discArtworkReader{
+				discNumber:     1,
+				imgFiles:       []string{f1, f2},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+			}
+
+			ff := reader.fromDiscArtPriority(ctx, nil, "disc*.*, cover.*")
+			Expect(ff).To(HaveLen(2))
+			r, path, err := ff[0]()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(path).To(Equal(f2))
+			r.Close()
+
+			ff = reader.fromDiscArtPriority(ctx, nil, "cover.*, disc*.*")
+			Expect(ff).To(HaveLen(2))
+			r, path, err = ff[0]()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(path).To(Equal(f1))
+			r.Close()
+		})
+
+		DescribeTable("numbered match wins over shared fallback within a pattern",
+			func(discNumber, expectedIdx int) {
+				files := []string{
+					createFile("album/disc.jpg"),
+					createFile("album/disc1.jpg"),
+					createFile("album/disc2.jpg"),
+				}
+				reader := &discArtworkReader{
+					discNumber:     discNumber,
+					imgFiles:       files,
+					discFoldersRel: map[string]bool{"album": true},
+					lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+				}
+
+				sf := reader.fromExternalFile(ctx, "disc*.*")
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				r.Close()
+				Expect(path).To(Equal(files[expectedIdx]))
+			},
+			Entry("disc 2 picks disc2.jpg over the shared disc.jpg", 2, 2),
+			Entry("disc 3 falls back to disc.jpg when no numbered match exists", 3, 0),
+		)
+
+		It("tries the next fallback candidate when the first one cannot be opened", func() {
+			f1 := createFile("album/cover.jpg")
+			f2 := createFile("album/cover.png")
+			// Remove f1 so Open will fail on it; f2 should still win.
+			removeFile(f1)
+			reader := &discArtworkReader{
+				discNumber:     1,
+				imgFiles:       []string{f1, f2},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+			}
+
+			sf := reader.fromExternalFile(ctx, "cover.*")
+			r, path, err := sf()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(r).ToNot(BeNil())
+			r.Close()
+			Expect(path).To(Equal(f2))
+		})
+
+		It("keeps scanning literal-pattern matches so fallback retry still works", func() {
+			// Guards against an 'early break on first literal match' optimization.
+			// Multiple imgFiles entries can share a basename (symlinks, case-variant
+			// duplicates on case-sensitive filesystems). If the loop breaks after
+			// recording just the first, the fallback retry cannot recover when
+			// that first file is unreadable.
+			f1 := createFile("album/stale/cover.png")
+			f2 := createFile("album/cover.png")
+			removeFile(f1)
+			reader := &discArtworkReader{
+				discNumber: 1,
+				imgFiles:   []string{f1, f2},
+				discFoldersRel: map[string]bool{
+					"album":       true,
+					"album/stale": true,
+				},
+				isMultiFolder: true,
+				lib:           libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+			}
+
+			sf := reader.fromExternalFile(ctx, "cover.png")
+			r, path, err := sf()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(r).ToNot(BeNil())
+			r.Close()
+			Expect(path).To(Equal(f2))
+		})
+
+		DescribeTable("filters by disc number for non-'*' wildcard patterns",
+			func(pattern string, discNumber, expectedIdx int) {
+				files := []string{
+					createFile("album/disc1.jpg"),
+					createFile("album/disc2.jpg"),
+				}
+				reader := &discArtworkReader{
+					discNumber:     discNumber,
+					imgFiles:       files,
+					discFoldersRel: map[string]bool{"album": true},
+					lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+				}
+
+				sf := reader.fromExternalFile(ctx, pattern)
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				r.Close()
+				Expect(path).To(Equal(files[expectedIdx]))
+			},
+			Entry("disc?.jpg, target disc 1 → disc1.jpg", "disc?.jpg", 1, 0),
+			Entry("disc?.jpg, target disc 2 → disc2.jpg", "disc?.jpg", 2, 1),
+			Entry("disc[0-9].jpg, target disc 1 → disc1.jpg", "disc[0-9].jpg", 1, 0),
+			Entry("disc[0-9].jpg, target disc 2 → disc2.jpg", "disc[0-9].jpg", 2, 1),
+		)
+
 		It("matches file without number in multi-folder album by folder", func() {
 			f1 := createFile("album/cd1/disc.jpg")
 			f2 := createFile("album/cd2/disc.jpg")
 			reader := &discArtworkReader{
-				discNumber:    1,
-				imgFiles:      []string{f1, f2},
-				discFolders:   map[string]bool{filepath.Join(tmpDir, "album", "cd1"): true},
-				isMultiFolder: true,
+				discNumber:     1,
+				imgFiles:       []string{f1, f2},
+				discFoldersRel: map[string]bool{"album/cd1": true},
+				isMultiFolder:  true,
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -120,10 +316,11 @@ var _ = Describe("Disc Artwork Reader", func() {
 			// disc2.jpg in cd1 folder should match disc 2, not disc 1
 			f1 := createFile("album/cd1/disc2.jpg")
 			reader := &discArtworkReader{
-				discNumber:    2,
-				imgFiles:      []string{f1},
-				discFolders:   map[string]bool{filepath.Join(tmpDir, "album", "cd1"): true},
-				isMultiFolder: true,
+				discNumber:     2,
+				imgFiles:       []string{f1},
+				discFoldersRel: map[string]bool{"album/cd1": true},
+				isMultiFolder:  true,
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -137,9 +334,10 @@ var _ = Describe("Disc Artwork Reader", func() {
 		It("does not match disc2.jpg when looking for disc 1", func() {
 			f1 := createFile("album/disc2.jpg")
 			reader := &discArtworkReader{
-				discNumber:  1,
-				imgFiles:    []string{f1},
-				discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+				discNumber:     1,
+				imgFiles:       []string{f1},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -159,11 +357,11 @@ var _ = Describe("Disc Artwork Reader", func() {
 			tmpDir = GinkgoT().TempDir()
 		})
 
-		createFile := func(path string) string {
-			fullPath := filepath.Join(tmpDir, filepath.FromSlash(path))
+		createFile := func(relPath string) string {
+			fullPath := filepath.Join(tmpDir, filepath.FromSlash(relPath))
 			Expect(os.MkdirAll(filepath.Dir(fullPath), 0755)).To(Succeed())
 			Expect(os.WriteFile(fullPath, []byte("image data"), 0600)).To(Succeed())
-			return fullPath
+			return relPath
 		}
 
 		It("matches image file whose stem equals the disc subtitle (case-insensitive)", func() {
@@ -171,6 +369,7 @@ var _ = Describe("Disc Artwork Reader", func() {
 			reader := &discArtworkReader{
 				discNumber: 1,
 				imgFiles:   []string{f1},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromDiscSubtitle(ctx, "The Blue Disc")
@@ -186,6 +385,7 @@ var _ = Describe("Disc Artwork Reader", func() {
 			reader := &discArtworkReader{
 				discNumber: 2,
 				imgFiles:   []string{f1},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromDiscSubtitle(ctx, "Bonus Tracks")
@@ -201,6 +401,7 @@ var _ = Describe("Disc Artwork Reader", func() {
 			reader := &discArtworkReader{
 				discNumber: 1,
 				imgFiles:   []string{f1},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromDiscSubtitle(ctx, "The Blue Disc")
@@ -214,6 +415,7 @@ var _ = Describe("Disc Artwork Reader", func() {
 			reader := &discArtworkReader{
 				discNumber: 1,
 				imgFiles:   []string{f1, f2},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromDiscSubtitle(ctx, "The Blue Disc")
@@ -227,19 +429,24 @@ var _ = Describe("Disc Artwork Reader", func() {
 
 	Describe("discArtworkReader", func() {
 		Describe("fromDiscArtPriority", func() {
-			var reader *discArtworkReader
+			var (
+				reader *discArtworkReader
+				tmpDir string
+			)
 
 			BeforeEach(func() {
+				tmpDir = GinkgoT().TempDir()
 				reader = &discArtworkReader{
-					discNumber:    2,
-					isMultiFolder: true,
-					discFolders:   map[string]bool{"/music/album/cd2": true},
+					discNumber:     2,
+					isMultiFolder:  true,
+					discFoldersRel: map[string]bool{"music/album/cd2": true},
 					imgFiles: []string{
-						"/music/album/cd1/disc.jpg",
-						"/music/album/cd2/disc.jpg",
-						"/music/album/cd2/disc2.jpg",
+						"music/album/cd1/disc.jpg",
+						"music/album/cd2/disc.jpg",
+						"music/album/cd2/disc2.jpg",
 					},
-					firstTrackPath: "/music/album/cd2/track1.flac",
+					firstTrackRel: "music/album/cd2/track1.flac",
+					lib:           libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 				}
 			})
 

core/artwork/reader_mediafile.go

@@ -15,6 +15,7 @@ type mediafileArtworkReader struct {
 	a         *artwork
 	mediafile model.MediaFile
 	album     model.Album
+	lib       libraryView
 }
 
 func newMediafileArtworkReader(ctx context.Context, artwork *artwork, artID model.ArtworkID) (*mediafileArtworkReader, error) {
@@ -30,10 +31,15 @@ func newMediafileArtworkReader(ctx context.Context, artwork *artwork, artID mode
 	if err != nil {
 		return nil, err
 	}
+	lib, err := loadLibraryView(ctx, artwork.ds, mf.LibraryID)
+	if err != nil {
+		return nil, err
+	}
 	a := &mediafileArtworkReader{
 		a:         artwork,
 		mediafile: *mf,
 		album:     *al,
+		lib:       lib,
 	}
 	a.cacheKey.artID = artID
 	a.cacheKey.lastUpdate = mf.UpdatedAt
@@ -60,10 +66,9 @@ func (a *mediafileArtworkReader) LastUpdated() time.Time {
 func (a *mediafileArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
 	var ff []sourceFunc
 	if a.mediafile.CoverArtID().Kind == model.KindMediaFileArtwork {
-		path := a.mediafile.AbsolutePath()
 		ff = []sourceFunc{
-			fromTag(ctx, path),
-			fromFFmpegTag(ctx, a.a.ffmpeg, path),
+			fromTag(ctx, a.lib.FS, a.mediafile.Path),
+			fromFFmpegTag(ctx, a.a.ffmpeg, a.lib.Abs(a.mediafile.Path)),
 		}
 	}
 	// For multi-disc albums, fall back to disc artwork first; for single-disc albums,

core/artwork/reader_resized.go

@@ -19,6 +19,16 @@ import (
 	xdraw "golang.org/x/image/draw"
 )
 
+func init() {
+	conf.AddHook(func() {
+		if err := webp.Dynamic(); err != nil {
+			log.Debug("Using WASM WebP encoder/decoder", "reason", err)
+		} else {
+			log.Debug("Using native libwebp for WebP encoding/decoding")
+		}
+	})
+}
+
 var bufPool = sync.Pool{
 	New: func() any {
 		return new(bytes.Buffer)
@@ -117,7 +127,7 @@ func (a *resizedArtworkReader) resizeImage(ctx context.Context, reader io.Reader
 }
 
 func resizeStaticImage(data []byte, size int, square bool) (io.Reader, int, error) {
-	original, _, err := image.Decode(bytes.NewReader(data))
+	original, format, err := image.Decode(bytes.NewReader(data))
 	if err != nil {
 		return nil, 0, err
 	}
@@ -157,14 +167,12 @@ func resizeStaticImage(data []byte, size int, square bool) (io.Reader, int, erro
 
 	buf := bufPool.Get().(*bytes.Buffer)
 	buf.Reset()
-	if conf.Server.DevJpegCoverArt {
-		if square {
-			err = png.Encode(buf, dst)
-		} else {
-			err = jpeg.Encode(buf, dst, &jpeg.Options{Quality: conf.Server.CoverArtQuality})
-		}
-	} else {
+	if conf.Server.EnableWebPEncoding {
 		err = webp.Encode(buf, dst, webp.Options{Quality: conf.Server.CoverArtQuality})
+	} else if format == "png" || square {
+		err = png.Encode(buf, dst)
+	} else {
+		err = jpeg.Encode(buf, dst, &jpeg.Options{Quality: conf.Server.CoverArtQuality})
 	}
 	if err != nil {
 		bufPool.Put(buf)

core/artwork/sources.go

@@ -5,9 +5,9 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"io/fs"
 	"net/http"
 	"net/url"
-	"os"
 	"path/filepath"
 	"reflect"
 	"regexp"
@@ -53,7 +53,7 @@ func (f sourceFunc) String() string {
 	return name
 }
 
-func fromExternalFile(ctx context.Context, files []string, pattern string) sourceFunc {
+func fromExternalFile(ctx context.Context, libFS fs.FS, files []string, pattern string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
 		for _, file := range files {
 			_, name := filepath.Split(file)
@@ -65,12 +65,12 @@ func fromExternalFile(ctx context.Context, files []string, pattern string) sourc
 			if !match {
 				continue
 			}
-			f, err := os.Open(file)
+			f, err := libFS.Open(file)
 			if err != nil {
 				log.Warn(ctx, "Could not open cover art file", "file", file, err)
 				continue
 			}
-			return f, file, err
+			return f, file, nil
 		}
 		return nil, "", fmt.Errorf("pattern '%s' not matched by files %v", pattern, files)
 	}
@@ -83,28 +83,43 @@ var picTypeRegexes = []*regexp.Regexp{
 	regexp.MustCompile(`(?i).*cover.*`),
 }
 
-func fromTag(ctx context.Context, path string) sourceFunc {
+func fromTag(ctx context.Context, libFS fs.FS, relPath string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
-		if path == "" {
+		if relPath == "" {
 			return nil, "", nil
 		}
-		f, err := taglib.OpenReadOnly(path, taglib.WithReadStyle(taglib.ReadStyleFast))
+		f, err := libFS.Open(relPath)
 		if err != nil {
 			return nil, "", err
 		}
+		rs, ok := f.(io.ReadSeeker)
+		if !ok {
+			f.Close()
+			return nil, "", fmt.Errorf("FS file %s is not seekable; cannot read tags", relPath)
+		}
+		tf, err := taglib.OpenStream(rs,
+			taglib.WithReadStyle(taglib.ReadStyleFast),
+			taglib.WithFilename(relPath),
+		)
+		if err != nil {
+			f.Close()
+			return nil, "", err
+		}
+		// Close in LIFO order: tf first (it holds rs internally), then f.
 		defer f.Close()
+		defer tf.Close()
 
-		images := f.Properties().Images
+		images := tf.Properties().Images
 		if len(images) == 0 {
-			return nil, "", fmt.Errorf("no embedded image found in %s", path)
+			return nil, "", fmt.Errorf("no embedded image found in %s", relPath)
 		}
 
-		imageIndex := findBestImageIndex(ctx, images, path)
-		data, err := f.Image(imageIndex)
+		imageIndex := findBestImageIndex(ctx, images, relPath)
+		data, err := tf.Image(imageIndex)
 		if err != nil || len(data) == 0 {
-			return nil, "", fmt.Errorf("could not load embedded image from %s", path)
+			return nil, "", fmt.Errorf("could not load embedded image from %s", relPath)
 		}
-		return io.NopCloser(bytes.NewReader(data)), path, nil
+		return io.NopCloser(bytes.NewReader(data)), relPath, nil
 	}
 }
 
@@ -121,6 +136,13 @@ func findBestImageIndex(ctx context.Context, images []taglib.ImageDesc, path str
 	return 0
 }
 
+// fromFFmpegTag is intentionally absolute-path-based. ffmpeg is a subprocess
+// and cannot read from arbitrary fs.FS implementations; piping via stdin is a
+// non-trivial refactor with stream/seek implications.
+//
+// TODO(artwork-musicfs): when the storage backing the library is not local
+// (e.g. a future S3 backend, or FakeFS in tests), short-circuit this source
+// func to return (nil, "", nil) so callers fall through cleanly.
 func fromFFmpegTag(ctx context.Context, ffmpeg ffmpeg.FFmpeg, path string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
 		if path == "" {

core/artwork/sources_internal_test.go

@@ -0,0 +1,92 @@
+package artwork
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"io/fs"
+	"os"
+	"testing/fstest"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("fromExternalFile", func() {
+	It("opens a matching file via the library FS", func() {
+		fsys := fstest.MapFS{
+			"Artist/Album/cover.jpg": &fstest.MapFile{Data: []byte("cover-bytes")},
+		}
+		f := fromExternalFile(GinkgoT().Context(), fsys, []string{"Artist/Album/cover.jpg"}, "cover.*")
+		r, path, err := f()
+		Expect(err).ToNot(HaveOccurred())
+		defer r.Close()
+		b, _ := io.ReadAll(r)
+		Expect(b).To(Equal([]byte("cover-bytes")))
+		Expect(path).To(Equal("Artist/Album/cover.jpg"))
+	})
+
+	It("returns an error when no file matches", func() {
+		fsys := fstest.MapFS{
+			"Artist/Album/something.txt": &fstest.MapFile{Data: []byte("x")},
+		}
+		f := fromExternalFile(GinkgoT().Context(), fsys, []string{"Artist/Album/something.txt"}, "cover.*")
+		_, _, err := f()
+		Expect(err).To(HaveOccurred())
+	})
+
+	It("skips files that fail to open and tries the next match", func() {
+		fsys := fstest.MapFS{
+			"a/cover.jpg": &fstest.MapFile{Data: []byte("a")},
+		}
+		// "missing/cover.jpg" is in candidates but not in the FS — should be skipped.
+		f := fromExternalFile(GinkgoT().Context(), fsys, []string{"missing/cover.jpg", "a/cover.jpg"}, "cover.*")
+		r, path, err := f()
+		Expect(err).ToNot(HaveOccurred())
+		defer r.Close()
+		b, _ := io.ReadAll(r)
+		Expect(b).To(Equal([]byte("a")))
+		Expect(path).To(Equal("a/cover.jpg"))
+	})
+})
+
+var _ = Describe("fromTag", func() {
+	It("opens an embedded image via fs.FS", func() {
+		fsys := os.DirFS("tests/fixtures/artist/an-album")
+		f := fromTag(GinkgoT().Context(), fsys, "test.mp3")
+		r, path, err := f()
+		Expect(err).ToNot(HaveOccurred())
+		defer r.Close()
+		Expect(path).To(Equal("test.mp3"))
+		b, _ := io.ReadAll(r)
+		Expect(b).ToNot(BeEmpty())
+	})
+
+	It("returns nil reader when the relative path is empty", func() {
+		f := fromTag(GinkgoT().Context(), os.DirFS("."), "")
+		r, _, err := f()
+		Expect(err).ToNot(HaveOccurred())
+		Expect(r).To(BeNil())
+	})
+
+	It("errors when the FS file is not seekable", func() {
+		fsys := nonSeekableFS{data: []byte("garbage")}
+		f := fromTag(GinkgoT().Context(), fsys, "x.mp3")
+		_, _, err := f()
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("not seekable"))
+	})
+})
+
+// nonSeekableFS is a single-file fs.FS whose Open returns a non-seekable file.
+type nonSeekableFS struct{ data []byte }
+
+func (n nonSeekableFS) Open(name string) (fs.File, error) {
+	return &nonSeekableFile{r: bytes.NewReader(n.data)}, nil
+}
+
+type nonSeekableFile struct{ r *bytes.Reader }
+
+func (n *nonSeekableFile) Read(p []byte) (int, error) { return n.r.Read(p) }
+func (n *nonSeekableFile) Close() error               { return nil }
+func (n *nonSeekableFile) Stat() (fs.FileInfo, error) { return nil, errors.New("not implemented") }

core/auth/claims.go

@@ -21,6 +21,7 @@ type Claims struct {
 	ID      string // "id" - artwork/mediafile ID
 	Format  string // "f" - audio format
 	BitRate int    // "b" - audio bitrate
+	ShareID string // "sid" - share ID for share stream tokens
 }
 
 // ToMap converts Claims to a map[string]any for use with TokenAuth.Encode().
@@ -54,6 +55,9 @@ func (c Claims) ToMap() map[string]any {
 	if c.BitRate != 0 {
 		m["b"] = c.BitRate
 	}
+	if c.ShareID != "" {
+		m["sid"] = c.ShareID
+	}
 	return m
 }
 
@@ -92,5 +96,9 @@ func ClaimsFromToken(token jwt.Token) Claims {
 			c.BitRate = int(bf)
 		}
 	}
+	var sid string
+	if err := token.Get("sid", &sid); err == nil {
+		c.ShareID = sid
+	}
 	return c
 }

core/auth/claims_test.go

@@ -28,6 +28,7 @@ var _ = Describe("Claims", func() {
 			Expect(m).NotTo(HaveKey("id"))
 			Expect(m).NotTo(HaveKey("f"))
 			Expect(m).NotTo(HaveKey("b"))
+			Expect(m).NotTo(HaveKey("sid"))
 		})
 
 		It("includes expiration and issued-at when set", func() {
@@ -52,6 +53,12 @@ var _ = Describe("Claims", func() {
 			Expect(m).To(HaveKeyWithValue("f", "mp3"))
 			Expect(m).To(HaveKeyWithValue("b", 192))
 		})
+
+		It("includes share ID claim when set", func() {
+			c := auth.Claims{ShareID: "abc1234567"}
+			m := c.ToMap()
+			Expect(m).To(HaveKeyWithValue("sid", "abc1234567"))
+		})
 	})
 
 	Describe("ClaimsFromToken", func() {
@@ -84,6 +91,7 @@ var _ = Describe("Claims", func() {
 				ID:      "al-456",
 				Format:  "opus",
 				BitRate: 128,
+				ShareID: "abc1234567",
 			}
 			token, _, err := tokenAuth.Encode(original.ToMap())
 			Expect(err).NotTo(HaveOccurred())
@@ -91,6 +99,7 @@ var _ = Describe("Claims", func() {
 			c := auth.ClaimsFromToken(token)
 			Expect(c.Issuer).To(Equal("ND"))
 			Expect(c.ID).To(Equal("al-456"))
+			Expect(c.ShareID).To(Equal("abc1234567"))
 			Expect(c.Format).To(Equal("opus"))
 			Expect(c.BitRate).To(Equal(128))
 		})

core/common_test.go

@@ -41,6 +41,7 @@ var _ = Describe("common.go", func() {
 		})
 
 		It("returns the absolute path when library exists", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-core)")
 			ctx := context.Background()
 			abs := AbsolutePath(ctx, ds, libId, path)
 			Expect(abs).To(Equal("/library/root/music/file.mp3"))

core/external/provider.go

@@ -12,6 +12,7 @@ import (
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils"
@@ -41,6 +42,7 @@ type Provider interface {
 type provider struct {
 	ds          model.DataStore
 	ag          Agents
+	matcher     *matcher.Matcher
 	artistQueue refreshQueue[auxArtist]
 	albumQueue  refreshQueue[auxAlbum]
 }
@@ -85,8 +87,8 @@ type Agents interface {
 	agents.SimilarSongsByArtistRetriever
 }
 
-func NewProvider(ds model.DataStore, agents Agents) Provider {
-	e := &provider{ds: ds, ag: agents}
+func NewProvider(ds model.DataStore, agents Agents, m *matcher.Matcher) Provider {
+	e := &provider{ds: ds, ag: agents, matcher: m}
 	e.artistQueue = newRefreshQueue(context.TODO(), e.populateArtistInfo)
 	e.albumQueue = newRefreshQueue(context.TODO(), e.populateAlbumInfo)
 	return e
@@ -300,7 +302,7 @@ func (e *provider) SimilarSongs(ctx context.Context, id string, count int) (mode
 	}
 
 	if err == nil && len(songs) > 0 {
-		return e.matchSongsToLibrary(ctx, songs, count)
+		return e.matcher.MatchSongs(ctx, songs, count)
 	}
 
 	// Fallback to existing similar artists + top songs algorithm
@@ -479,7 +481,7 @@ func (e *provider) getMatchingTopSongs(ctx context.Context, agent agents.ArtistT
 		}
 	}
 
-	mfs, err := e.matchSongsToLibrary(ctx, songs, count)
+	mfs, err := e.matcher.MatchSongs(ctx, songs, count)
 	if err != nil {
 		return nil, err
 	}

core/external/provider_albumimage_test.go

@@ -9,6 +9,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/agents"
 	. "github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -43,7 +44,7 @@ var _ = Describe("Provider - AlbumImage", func() {
 		mockAlbumAgent = newMockAlbumInfoAgent()
 
 		agentsCombined := &mockAgents{albumInfoAgent: mockAlbumAgent}
-		provider = NewProvider(ds, agentsCombined)
+		provider = NewProvider(ds, agentsCombined, matcher.New(ds))
 
 		// Default mocks
 		// Mocks for GetEntityByID sequence (initial failed lookups)

core/external/provider_artistimage_test.go

@@ -11,6 +11,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/agents"
 	. "github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
@@ -51,7 +52,7 @@ var _ = Describe("Provider - ArtistImage", func() {
 			imageAgent: mockImageAgent,
 		}
 
-		provider = NewProvider(ds, agentsCombined)
+		provider = NewProvider(ds, agentsCombined, matcher.New(ds))
 
 		// Default mocks for successful Get calls
 		mockArtistRepo.On("Get", "artist-1").Return(&model.Artist{ID: "artist-1", Name: "Artist One"}, nil).Maybe()

core/external/provider_matching_test.go

@@ -1,762 +0,0 @@
-package external_test
-
-import (
-	"context"
-
-	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/conf/configtest"
-	"github.com/navidrome/navidrome/core/agents"
-	. "github.com/navidrome/navidrome/core/external"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/tests"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-	"github.com/stretchr/testify/mock"
-)
-
-var _ = Describe("Provider - Song Matching", func() {
-	var ds model.DataStore
-	var provider Provider
-	var agentsCombined *mockAgents
-	var artistRepo *mockArtistRepo
-	var mediaFileRepo *mockMediaFileRepo
-	var albumRepo *mockAlbumRepo
-	var ctx context.Context
-
-	BeforeEach(func() {
-		ctx = GinkgoT().Context()
-
-		artistRepo = newMockArtistRepo()
-		mediaFileRepo = newMockMediaFileRepo()
-		albumRepo = newMockAlbumRepo()
-
-		ds = &tests.MockDataStore{
-			MockedArtist:    artistRepo,
-			MockedMediaFile: mediaFileRepo,
-			MockedAlbum:     albumRepo,
-		}
-
-		agentsCombined = &mockAgents{}
-		provider = NewProvider(ds, agentsCombined)
-	})
-
-	// Shared helper for tests that only need artist track queries (no ID/MBID matching)
-	setupSimilarSongsExpectations := func(returnedSongs []agents.Song, artistTracks model.MediaFiles) {
-		agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
-			Return(returnedSongs, nil).Once()
-
-		// loadTracksByTitleAndArtist - queries by artist name
-		mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			and, ok := opt.Filters.(squirrel.And)
-			if !ok || len(and) < 2 {
-				return false
-			}
-			eq, hasEq := and[0].(squirrel.Eq)
-			if !hasEq {
-				return false
-			}
-			_, hasArtist := eq["order_artist_name"]
-			return hasArtist
-		})).Return(artistTracks, nil).Maybe()
-	}
-
-	Describe("matchSongsToLibrary priority matching", func() {
-		var track model.MediaFile
-
-		BeforeEach(func() {
-			DeferCleanup(configtest.SetupConfig())
-			// Disable fuzzy matching for these tests to avoid unexpected GetAll calls
-			conf.Server.SimilarSongsMatchThreshold = 100
-
-			track = model.MediaFile{ID: "track-1", Title: "Test Track", Artist: "Test Artist", MbzRecordingID: ""}
-
-			// Setup for GetEntityByID to return the track
-			artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
-			albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
-			mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
-		})
-
-		setupExpectations := func(returnedSongs []agents.Song, idMatches, mbidMatches, artistTracks model.MediaFiles) {
-			agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
-				Return(returnedSongs, nil).Once()
-
-			// loadTracksByID
-			mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-				_, ok := opt.Filters.(squirrel.Eq)
-				return ok
-			})).Return(idMatches, nil).Once()
-
-			// loadTracksByMBID
-			mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-				and, ok := opt.Filters.(squirrel.And)
-				if !ok || len(and) < 1 {
-					return false
-				}
-				eq, hasEq := and[0].(squirrel.Eq)
-				if !hasEq {
-					return false
-				}
-				_, hasMBID := eq["mbz_recording_id"]
-				return hasMBID
-			})).Return(mbidMatches, nil).Once()
-
-			// loadTracksByTitleAndArtist - now queries by artist name
-			mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-				and, ok := opt.Filters.(squirrel.And)
-				if !ok || len(and) < 2 {
-					return false
-				}
-				eq, hasEq := and[0].(squirrel.Eq)
-				if !hasEq {
-					return false
-				}
-				_, hasArtist := eq["order_artist_name"]
-				return hasArtist
-			})).Return(artistTracks, nil).Maybe()
-		}
-
-		Context("when agent returns artist and album metadata", func() {
-			It("matches by title + artist MBID + album MBID (highest priority)", func() {
-				// Song in library with all MBIDs
-				correctMatch := model.MediaFile{
-					ID: "correct-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Violator",
-					MbzArtistID: "artist-mbid-123", MbzAlbumID: "album-mbid-456",
-				}
-				// Another song with same title but different MBIDs (should NOT match)
-				wrongMatch := model.MediaFile{
-					ID: "wrong-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Some Other Album",
-					MbzArtistID: "artist-mbid-123", MbzAlbumID: "different-album-mbid",
-				}
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song", Artist: "Depeche Mode", ArtistMBID: "artist-mbid-123", Album: "Violator", AlbumMBID: "album-mbid-456"},
-				}
-
-				setupExpectations(returnedSongs, model.MediaFiles{}, model.MediaFiles{}, model.MediaFiles{wrongMatch, correctMatch})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("correct-match"))
-			})
-
-			It("matches by title + artist name + album name when MBIDs unavailable", func() {
-				// Song in library without MBIDs but with matching artist/album names
-				correctMatch := model.MediaFile{
-					ID: "correct-match", Title: "Similar Song", Artist: "depeche mode", Album: "violator",
-				}
-				// Another song with same title but different artist (should NOT match)
-				wrongMatch := model.MediaFile{
-					ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
-				}
-
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song", Artist: "Depeche Mode", Album: "Violator"}, // No MBIDs
-				}
-
-				setupExpectations(returnedSongs, model.MediaFiles{}, model.MediaFiles{}, model.MediaFiles{wrongMatch, correctMatch})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("correct-match"))
-			})
-
-			It("matches by title + artist only when album info unavailable", func() {
-				// Song in library with matching artist
-				correctMatch := model.MediaFile{
-					ID: "correct-match", Title: "Similar Song", Artist: "depeche mode", Album: "Some Album",
-				}
-				// Another song with same title but different artist
-				wrongMatch := model.MediaFile{
-					ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
-				}
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song", Artist: "Depeche Mode"}, // No album info
-				}
-
-				setupExpectations(returnedSongs, model.MediaFiles{}, model.MediaFiles{}, model.MediaFiles{wrongMatch, correctMatch})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("correct-match"))
-			})
-
-			It("does not match songs without artist info", func() {
-				// Songs without artist info cannot be matched since we query by artist
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song"}, // No artist/album info at all
-				}
-
-				// No artist to query, so no GetAll calls for title matching
-				setupExpectations(returnedSongs, model.MediaFiles{}, model.MediaFiles{}, model.MediaFiles{})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(BeEmpty())
-			})
-		})
-
-		Context("when matching multiple songs with the same title but different artists", func() {
-			It("returns distinct matches for each artist's version (covers scenario)", func() {
-				// Multiple covers of the same song by different artists
-				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",
-				}
-
-				returnedSongs := []agents.Song{
-					{Name: "Yesterday", Artist: "The Beatles", Album: "Help!"},
-					{Name: "Yesterday", Artist: "Ray Charles", Album: "Greatest Hits"},
-					{Name: "Yesterday", Artist: "Frank Sinatra", Album: "My Way"},
-				}
-
-				setupExpectations(returnedSongs, model.MediaFiles{}, model.MediaFiles{}, model.MediaFiles{cover1, cover2, cover3})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				// All three covers should be returned, not just the first one
-				Expect(songs).To(HaveLen(3))
-				// Verify all three different versions are included
-				ids := []string{songs[0].ID, songs[1].ID, songs[2].ID}
-				Expect(ids).To(ContainElements("cover-1", "cover-2", "cover-3"))
-			})
-		})
-
-		Context("when matching multiple songs with different precision levels", func() {
-			It("prefers more precise matches for each song", func() {
-				// Library has multiple versions of same song
-				preciseMatch := model.MediaFile{
-					ID: "precise", Title: "Song A", Artist: "Artist One", Album: "Album One",
-					MbzArtistID: "mbid-1", MbzAlbumID: "album-mbid-1",
-				}
-				lessAccurateMatch := model.MediaFile{
-					ID: "less-accurate", Title: "Song A", Artist: "Artist One", Album: "Compilation",
-					MbzArtistID: "mbid-1",
-				}
-				artistTwoMatch := model.MediaFile{
-					ID: "artist-two", Title: "Song B", Artist: "Artist Two",
-				}
-
-				returnedSongs := []agents.Song{
-					{Name: "Song A", Artist: "Artist One", ArtistMBID: "mbid-1", Album: "Album One", AlbumMBID: "album-mbid-1"},
-					{Name: "Song B", Artist: "Artist Two"}, // Different artist
-				}
-
-				setupExpectations(returnedSongs, model.MediaFiles{}, model.MediaFiles{}, model.MediaFiles{lessAccurateMatch, preciseMatch, artistTwoMatch})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(2))
-				// First song should be the precise match (has all MBIDs)
-				Expect(songs[0].ID).To(Equal("precise"))
-				// Second song matches by title + artist
-				Expect(songs[1].ID).To(Equal("artist-two"))
-			})
-		})
-	})
-
-	Describe("Fuzzy matching fallback", func() {
-		var track model.MediaFile
-
-		BeforeEach(func() {
-			DeferCleanup(configtest.SetupConfig())
-			track = model.MediaFile{ID: "track-1", Title: "Test Track", Artist: "Test Artist"}
-
-			// Setup for GetEntityByID to return the track
-			artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
-			albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
-			mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
-		})
-
-		Context("with default threshold (85%)", func() {
-			It("matches songs with remastered suffix", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
-
-				// Agent returns "Paranoid Android" but library has "Paranoid Android - Remastered"
-				returnedSongs := []agents.Song{
-					{Name: "Paranoid Android", Artist: "Radiohead"},
-				}
-				// Artist catalog has the remastered version (fuzzy match will find it)
-				artistTracks := model.MediaFiles{
-					{ID: "remastered", Title: "Paranoid Android - Remastered", Artist: "Radiohead"},
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, artistTracks)
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("remastered"))
-			})
-
-			It("matches songs with live suffix", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
-
-				returnedSongs := []agents.Song{
-					{Name: "Bohemian Rhapsody", Artist: "Queen"},
-				}
-				artistTracks := model.MediaFiles{
-					{ID: "live", Title: "Bohemian Rhapsody (Live)", Artist: "Queen"},
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, artistTracks)
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("live"))
-			})
-
-			It("does not match completely different songs", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
-
-				returnedSongs := []agents.Song{
-					{Name: "Yesterday", Artist: "The Beatles"},
-				}
-				// Artist catalog has completely different songs
-				artistTracks := model.MediaFiles{
-					{ID: "different", Title: "Tomorrow Never Knows", Artist: "The Beatles"},
-					{ID: "different2", Title: "Here Comes The Sun", Artist: "The Beatles"},
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, artistTracks)
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(BeEmpty())
-			})
-		})
-
-		Context("with threshold set to 100 (exact match only)", func() {
-			It("only matches exact titles", func() {
-				conf.Server.SimilarSongsMatchThreshold = 100
-
-				returnedSongs := []agents.Song{
-					{Name: "Paranoid Android", Artist: "Radiohead"},
-				}
-				// Artist catalog has only remastered version - no exact match
-				artistTracks := model.MediaFiles{
-					{ID: "remastered", Title: "Paranoid Android - Remastered", Artist: "Radiohead"},
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, artistTracks)
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(BeEmpty())
-			})
-		})
-
-		Context("with lower threshold (75%)", func() {
-			It("matches more aggressively", func() {
-				conf.Server.SimilarSongsMatchThreshold = 75
-
-				returnedSongs := []agents.Song{
-					{Name: "Song", Artist: "Artist"},
-				}
-				artistTracks := model.MediaFiles{
-					{ID: "extended", Title: "Song (Extended Mix)", Artist: "Artist"},
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, artistTracks)
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("extended"))
-			})
-		})
-
-		Context("with fuzzy album matching", func() {
-			It("matches album with (Remaster) suffix", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
-
-				// Agent returns "A Night at the Opera" but library has remastered version
-				returnedSongs := []agents.Song{
-					{Name: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera"},
-				}
-				// Library has same album with remaster suffix
-				correctMatch := model.MediaFile{
-					ID: "correct", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera (2011 Remaster)",
-				}
-				wrongMatch := model.MediaFile{
-					ID: "wrong", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "Greatest Hits",
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{wrongMatch, correctMatch})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				// Should prefer the fuzzy album match (Level 3) over title+artist only (Level 1)
-				Expect(songs[0].ID).To(Equal("correct"))
-			})
-
-			It("matches album with (Deluxe Edition) suffix", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
-
-				returnedSongs := []agents.Song{
-					{Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"},
-				}
-				correctMatch := model.MediaFile{
-					ID: "correct", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator (Deluxe Edition)",
-				}
-				wrongMatch := model.MediaFile{
-					ID: "wrong", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "101",
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{wrongMatch, correctMatch})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("correct"))
-			})
-
-			It("prefers exact album match over fuzzy album match", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
-
-				returnedSongs := []agents.Song{
-					{Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"},
-				}
-				exactMatch := model.MediaFile{
-					ID: "exact", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator",
-				}
-				fuzzyMatch := model.MediaFile{
-					ID: "fuzzy", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator (Deluxe Edition)",
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{fuzzyMatch, exactMatch})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				// Both have same title similarity (1.0), so should prefer exact album match (higher specificity via higher album similarity)
-				Expect(songs[0].ID).To(Equal("exact"))
-			})
-		})
-	})
-
-	Describe("Duration matching", func() {
-		var track model.MediaFile
-
-		BeforeEach(func() {
-			DeferCleanup(configtest.SetupConfig())
-			conf.Server.SimilarSongsMatchThreshold = 100 // Exact title match for predictable tests
-
-			track = model.MediaFile{ID: "track-1", Title: "Test Track", Artist: "Test Artist"}
-
-			// Setup for GetEntityByID to return the track
-			artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
-			albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
-			mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
-		})
-
-		Context("when agent provides duration", func() {
-			It("prefers tracks with matching duration", func() {
-				// Agent returns song with duration 180000ms (180 seconds)
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
-				}
-				// Library has two versions: one matching duration, one not
-				correctMatch := model.MediaFile{
-					ID: "correct", Title: "Similar Song", Artist: "Test Artist", Duration: 180.0,
-				}
-				wrongDuration := model.MediaFile{
-					ID: "wrong", Title: "Similar Song", Artist: "Test Artist", Duration: 240.0,
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{wrongDuration, correctMatch})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("correct"))
-			})
-
-			It("matches tracks with close duration", func() {
-				// Agent returns song with duration 180000ms (180 seconds)
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
-				}
-				// Library has track with 182.5 seconds (close to target)
-				closeDuration := model.MediaFile{
-					ID: "close-duration", Title: "Similar Song", Artist: "Test Artist", Duration: 182.5,
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{closeDuration})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("close-duration"))
-			})
-
-			It("prefers closer duration over farther duration", func() {
-				// Agent returns song with duration 180000ms (180 seconds)
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
-				}
-				// Library has one close, one far
-				closeDuration := model.MediaFile{
-					ID: "close", Title: "Similar Song", Artist: "Test Artist", Duration: 181.0,
-				}
-				farDuration := model.MediaFile{
-					ID: "far", Title: "Similar Song", Artist: "Test Artist", Duration: 190.0,
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{farDuration, closeDuration})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("close"))
-			})
-
-			It("still matches when no tracks have matching duration", func() {
-				// Agent returns song with duration 180000ms
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
-				}
-				// Library only has tracks with very different duration
-				differentDuration := model.MediaFile{
-					ID: "different", Title: "Similar Song", Artist: "Test Artist", Duration: 300.0,
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{differentDuration})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				// Duration mismatch doesn't exclude the track; it's just scored lower
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("different"))
-			})
-
-			It("prefers title match over duration match when titles differ", func() {
-				// Agent returns "Similar Song" with duration 180000ms
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
-				}
-				// Library has:
-				// - differentTitle: matches duration but has different title (won't pass title threshold)
-				// - correctTitle: doesn't match duration but has correct title (wins on title similarity)
-				differentTitle := model.MediaFile{
-					ID: "wrong-title", Title: "Different Song", Artist: "Test Artist", Duration: 180.0,
-				}
-				correctTitle := model.MediaFile{
-					ID: "correct-title", Title: "Similar Song", Artist: "Test Artist", Duration: 300.0,
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{differentTitle, correctTitle})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				// Title similarity is the top priority, so the correct title wins despite duration mismatch
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("correct-title"))
-			})
-		})
-
-		Context("when agent does not provide duration", func() {
-			It("matches without duration filtering (duration=0)", func() {
-				// Agent returns song without duration
-				returnedSongs := []agents.Song{
-					{Name: "Similar Song", Artist: "Test Artist", Duration: 0},
-				}
-				// Library tracks with various durations should all be candidates
-				anyTrack := model.MediaFile{
-					ID: "any", Title: "Similar Song", Artist: "Test Artist", Duration: 999.0,
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{anyTrack})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("any"))
-			})
-		})
-
-		Context("edge cases", func() {
-			It("handles very short songs with close duration", func() {
-				// 30-second song with 1-second difference
-				returnedSongs := []agents.Song{
-					{Name: "Short Song", Artist: "Test Artist", Duration: 30000},
-				}
-				shortTrack := model.MediaFile{
-					ID: "short", Title: "Short Song", Artist: "Test Artist", Duration: 31.0,
-				}
-
-				setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{shortTrack})
-
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-				Expect(err).ToNot(HaveOccurred())
-				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("short"))
-			})
-		})
-	})
-
-	Describe("Deduplication of mismatched songs", func() {
-		var track model.MediaFile
-
-		BeforeEach(func() {
-			DeferCleanup(configtest.SetupConfig())
-			conf.Server.SimilarSongsMatchThreshold = 85 // Allow fuzzy matching
-
-			track = model.MediaFile{ID: "track-1", Title: "Test Track", Artist: "Test Artist"}
-
-			// Setup for GetEntityByID to return the track
-			artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
-			albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
-			mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
-		})
-
-		It("removes duplicates when different input songs match the same library track", func() {
-			// Agent returns two different versions that will both fuzzy-match to the same library track
-			returnedSongs := []agents.Song{
-				{Name: "Bohemian Rhapsody (Live)", Artist: "Queen"},
-				{Name: "Bohemian Rhapsody (Original Mix)", Artist: "Queen"},
-			}
-			// Library only has one version
-			libraryTrack := model.MediaFile{
-				ID: "br-live", Title: "Bohemian Rhapsody (Live)", Artist: "Queen",
-			}
-
-			setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{libraryTrack})
-
-			songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-			Expect(err).ToNot(HaveOccurred())
-			// Should only return one track, not two duplicates
-			Expect(songs).To(HaveLen(1))
-			Expect(songs[0].ID).To(Equal("br-live"))
-		})
-
-		It("preserves duplicates when identical input songs match the same library track", func() {
-			// Agent returns the exact same song twice (intentional repetition)
-			returnedSongs := []agents.Song{
-				{Name: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera"},
-				{Name: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera"},
-			}
-			// Library has matching track
-			libraryTrack := model.MediaFile{
-				ID: "br", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera",
-			}
-
-			setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{libraryTrack})
-
-			songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-			Expect(err).ToNot(HaveOccurred())
-			// Should return two tracks since input songs were identical
-			Expect(songs).To(HaveLen(2))
-			Expect(songs[0].ID).To(Equal("br"))
-			Expect(songs[1].ID).To(Equal("br"))
-		})
-
-		It("handles mixed scenario with both identical and different input songs", func() {
-			// Agent returns: Song A, Song B (different from A), Song A again (same as first)
-			// All three match to the same library track
-			returnedSongs := []agents.Song{
-				{Name: "Yesterday", Artist: "The Beatles", Album: "Help!"},
-				{Name: "Yesterday (Remastered)", Artist: "The Beatles", Album: "1"},        // Different version
-				{Name: "Yesterday", Artist: "The Beatles", Album: "Help!"},                 // Same as first
-				{Name: "Yesterday (Anthology)", Artist: "The Beatles", Album: "Anthology"}, // Another different version
-			}
-			// Library only has one version
-			libraryTrack := model.MediaFile{
-				ID: "yesterday", Title: "Yesterday", Artist: "The Beatles", Album: "Help!",
-			}
-
-			setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{libraryTrack})
-
-			songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-			Expect(err).ToNot(HaveOccurred())
-			// Should return 2 tracks:
-			// 1. First "Yesterday" (original)
-			// 2. Third "Yesterday" (same as first, so kept)
-			// Skip: Second "Yesterday (Remastered)" (different input, same library track)
-			// Skip: Fourth "Yesterday (Anthology)" (different input, same library track)
-			Expect(songs).To(HaveLen(2))
-			Expect(songs[0].ID).To(Equal("yesterday"))
-			Expect(songs[1].ID).To(Equal("yesterday"))
-		})
-
-		It("does not deduplicate songs that match different library tracks", func() {
-			// Agent returns different songs that match different library tracks
-			returnedSongs := []agents.Song{
-				{Name: "Song A", Artist: "Artist"},
-				{Name: "Song B", Artist: "Artist"},
-				{Name: "Song C", Artist: "Artist"},
-			}
-			// Library has all three songs
-			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"}
-
-			setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{trackA, trackB, trackC})
-
-			songs, err := provider.SimilarSongs(ctx, "track-1", 5)
-
-			Expect(err).ToNot(HaveOccurred())
-			// All three should be returned since they match different library tracks
-			Expect(songs).To(HaveLen(3))
-			Expect(songs[0].ID).To(Equal("track-a"))
-			Expect(songs[1].ID).To(Equal("track-b"))
-			Expect(songs[2].ID).To(Equal("track-c"))
-		})
-
-		It("respects count limit after deduplication", func() {
-			// Agent returns 4 songs: 2 unique + 2 that would create duplicates
-			returnedSongs := []agents.Song{
-				{Name: "Song A", Artist: "Artist"},
-				{Name: "Song A (Live)", Artist: "Artist"}, // Different, matches same track
-				{Name: "Song B", Artist: "Artist"},
-				{Name: "Song B (Remix)", Artist: "Artist"}, // Different, matches same track
-			}
-			trackA := model.MediaFile{ID: "track-a", Title: "Song A", Artist: "Artist"}
-			trackB := model.MediaFile{ID: "track-b", Title: "Song B", Artist: "Artist"}
-
-			setupSimilarSongsExpectations(returnedSongs, model.MediaFiles{trackA, trackB})
-
-			// Request only 2 songs
-			songs, err := provider.SimilarSongs(ctx, "track-1", 2)
-
-			Expect(err).ToNot(HaveOccurred())
-			// Should return exactly 2: Song A and Song B (skipping duplicates)
-			Expect(songs).To(HaveLen(2))
-			Expect(songs[0].ID).To(Equal("track-a"))
-			Expect(songs[1].ID).To(Equal("track-b"))
-		})
-	})
-})

core/external/provider_similarsongs_test.go

@@ -7,6 +7,7 @@ import (
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/core/agents"
 	. "github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -48,7 +49,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 			similarAgent:  mockSimilarAgent,
 		}
 
-		provider = NewProvider(ds, agentsCombined)
+		provider = NewProvider(ds, agentsCombined, matcher.New(ds))
 	})
 
 	Describe("dispatch by entity type", func() {

core/external/provider_topsongs_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/agents"
 	. "github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -29,7 +30,7 @@ var _ = Describe("Provider - TopSongs", func() {
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 		// Disable fuzzy matching for these tests to avoid unexpected GetAll calls
-		conf.Server.SimilarSongsMatchThreshold = 100
+		conf.Server.Matcher.FuzzyThreshold = 100
 
 		ctx = GinkgoT().Context()
 
@@ -44,7 +45,7 @@ var _ = Describe("Provider - TopSongs", func() {
 
 		ag = new(mockAgents)
 
-		p = NewProvider(ds, ag)
+		p = NewProvider(ds, ag, matcher.New(ds))
 	})
 
 	It("returns top songs for a known artist", func() {

core/external/provider_updatealbuminfo_test.go

@@ -8,6 +8,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
@@ -34,7 +35,7 @@ var _ = Describe("Provider - UpdateAlbumInfo", func() {
 		ctx = GinkgoT().Context()
 		ds = new(tests.MockDataStore)
 		ag = new(mockAgents)
-		p = external.NewProvider(ds, ag)
+		p = external.NewProvider(ds, ag, matcher.New(ds))
 		mockAlbumRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
 		conf.Server.DevAlbumInfoTimeToLive = 1 * time.Hour
 	})

core/external/provider_updateartistinfo_test.go

@@ -9,6 +9,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
@@ -37,7 +38,7 @@ var _ = Describe("Provider - UpdateArtistInfo", func() {
 		ctx = GinkgoT().Context()
 		ds = new(tests.MockDataStore)
 		ag = new(mockAgents)
-		p = external.NewProvider(ds, ag)
+		p = external.NewProvider(ds, ag, matcher.New(ds))
 		mockArtistRepo = ds.Artist(ctx).(*tests.MockArtistRepo)
 	})
 
@@ -104,6 +105,29 @@ var _ = Describe("Provider - UpdateArtistInfo", func() {
 		ag.AssertExpectations(GinkgoT())
 	})
 
+	It("preserves decoded plain text in biography storage", func() {
+		originalArtist := &model.Artist{
+			ID:   "ar-encoded-bio",
+			Name: "Encoded Bio Artist",
+		}
+		mockArtistRepo.SetData(model.Artists{*originalArtist})
+
+		expectedMBID := "mbid-encoded-bio"
+		expectedBio := "R&B"
+
+		ag.On("GetArtistMBID", ctx, "ar-encoded-bio", "Encoded Bio Artist").Return(expectedMBID, nil).Once()
+		ag.On("GetArtistImages", ctx, "ar-encoded-bio", "Encoded Bio Artist", expectedMBID).Return(nil, nil).Maybe()
+		ag.On("GetArtistBiography", ctx, "ar-encoded-bio", "Encoded Bio Artist", expectedMBID).Return(expectedBio, nil).Once()
+		ag.On("GetArtistURL", ctx, "ar-encoded-bio", "Encoded Bio Artist", expectedMBID).Return("", nil).Maybe()
+		ag.On("GetSimilarArtists", ctx, "ar-encoded-bio", "Encoded Bio Artist", expectedMBID, 100).Return(nil, nil).Maybe()
+
+		updatedArtist, err := p.UpdateArtistInfo(ctx, "ar-encoded-bio", 10, false)
+
+		Expect(err).NotTo(HaveOccurred())
+		Expect(updatedArtist).NotTo(BeNil())
+		Expect(updatedArtist.Biography).To(Equal("R&B"))
+	})
+
 	It("returns cached info when artist exists and info is not expired", func() {
 		now := time.Now()
 		originalArtist := &model.Artist{

core/ffmpeg/ffmpeg.go

@@ -13,6 +13,7 @@ import (
 	"strconv"
 	"strings"
 	"sync"
+	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
@@ -49,6 +50,7 @@ type FFmpeg interface {
 	ProbeAudioStream(ctx context.Context, filePath string) (*AudioProbeResult, error)
 	CmdPath() (string, error)
 	IsAvailable() bool
+	IsProbeAvailable() bool
 	Version() string
 }
 
@@ -56,6 +58,11 @@ func New() FFmpeg {
 	return &ffmpeg{}
 }
 
+// ErrAnimatedWebPUnsupported is returned by ConvertAnimatedImage when the
+// ffmpeg binary lacks the libwebp_anim encoder. Callers can use errors.Is to
+// detect this specific case and fall back to static resize.
+var ErrAnimatedWebPUnsupported = errors.New("ffmpeg lacks libwebp_anim encoder — install an ffmpeg build with libwebp")
+
 const (
 	extractImageCmd     = "ffmpeg -i %s -map 0:v -map -0:V -vcodec copy -f image2pipe -"
 	probeCmd            = "ffmpeg %s -f ffmetadata"
@@ -85,6 +92,9 @@ func (e *ffmpeg) ConvertAnimatedImage(ctx context.Context, reader io.Reader, max
 	if err != nil {
 		return nil, err
 	}
+	if !animWebP.has(cmdPath, "libwebp_anim") {
+		return nil, ErrAnimatedWebPUnsupported
+	}
 
 	args := []string{cmdPath, "-i", "pipe:0"}
 	if maxSize > 0 {
@@ -97,6 +107,19 @@ func (e *ffmpeg) ConvertAnimatedImage(ctx context.Context, reader io.Reader, max
 	return e.start(ctx, args, reader)
 }
 
+// parseEncodersOutput scans the stdout of `ffmpeg -encoders` for a whole-word
+// match of encoder name. The output has rows like " V....D libwebp_anim  ..."
+// where the name is the 2nd whitespace-separated field.
+func parseEncodersOutput(out []byte, name string) bool {
+	for line := range strings.SplitSeq(string(out), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) >= 2 && fields[1] == name {
+			return true
+		}
+	}
+	return false
+}
+
 func (e *ffmpeg) ExtractImage(ctx context.Context, path string) (io.ReadCloser, error) {
 	if _, err := ffmpegCmd(); err != nil {
 		return nil, err
@@ -224,6 +247,19 @@ func (e *ffmpeg) IsAvailable() bool {
 	return err == nil
 }
 
+func (e *ffmpeg) IsProbeAvailable() bool {
+	if _, err := ffmpegCmd(); err != nil {
+		return false
+	}
+	probeOnce.Do(func() {
+		probePath := ffprobePath(ffmpegPath)
+		if _, err := exec.LookPath(probePath); err == nil {
+			probeAvail = true
+		}
+	})
+	return probeAvail
+}
+
 // Version executes ffmpeg -version and extracts the version from the output.
 // Sample output: ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers
 func (e *ffmpeg) Version() string {
@@ -373,18 +409,7 @@ func buildDynamicArgs(opts TranscodeOptions) []string {
 	if opts.BitRate > 0 {
 		args = append(args, "-b:a", strconv.Itoa(opts.BitRate)+"k")
 	}
-	if opts.SampleRate > 0 {
-		args = append(args, "-ar", strconv.Itoa(opts.SampleRate))
-	}
-	if opts.Channels > 0 {
-		args = append(args, "-ac", strconv.Itoa(opts.Channels))
-	}
-	// Only pass -sample_fmt for lossless output formats where bit depth matters.
-	// Lossy codecs (mp3, aac, opus) handle sample format conversion internally,
-	// and passing interleaved formats like "s16" causes silent failures.
-	if opts.BitDepth >= 16 && isLosslessOutputFormat(opts.Format) {
-		args = append(args, "-sample_fmt", bitDepthToSampleFmt(opts.BitDepth))
-	}
+	args = injectDynamicAudioFlags(args, opts)
 
 	args = append(args, "-v", "0")
 
@@ -398,12 +423,19 @@ func buildDynamicArgs(opts TranscodeOptions) []string {
 
 // buildTemplateArgs handles user-customized command templates, with dynamic injection
 // of sample rate, channels, and bit depth when requested by the transcode decision.
-// Note: these flags are injected unconditionally when non-zero, even if the template
-// already includes them. FFmpeg uses the last occurrence of duplicate flags.
+// Values in opts have already been clamped to codec limits upstream (see
+// core/stream/codec.go codecMax* helpers), so injecting them unconditionally is safe —
+// ffmpeg honors the last occurrence of a duplicate flag.
 func buildTemplateArgs(opts TranscodeOptions) []string {
 	args := createFFmpegCommand(opts.Command, opts.FilePath, opts.BitRate, opts.Offset)
+	return injectDynamicAudioFlags(args, opts)
+}
 
-	// Dynamically inject -ar, -ac, and -sample_fmt before the output target
+// injectDynamicAudioFlags appends -ar, -ac, and -sample_fmt flags based on opts.
+// Only passes -sample_fmt for lossless output formats where bit depth matters:
+// lossy codecs (mp3, aac, opus) handle sample format conversion internally, and
+// passing interleaved formats like "s16" causes silent failures.
+func injectDynamicAudioFlags(args []string, opts TranscodeOptions) []string {
 	if opts.SampleRate > 0 {
 		args = injectBeforeOutput(args, "-ar", strconv.Itoa(opts.SampleRate))
 	}
@@ -528,9 +560,55 @@ func ffmpegCmd() (string, error) {
 	return ffmpegPath, ffmpegErr
 }
 
+type encoderProbeState uint8
+
+const (
+	encoderProbeUnknown encoderProbeState = iota
+	encoderProbeAvailable
+	encoderProbeUnavailable
+)
+
+type encoderProbe struct {
+	mu    sync.Mutex
+	state encoderProbeState
+}
+
+func (p *encoderProbe) has(cmdPath, encoder string) bool {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	switch p.state {
+	case encoderProbeAvailable:
+		return true
+	case encoderProbeUnavailable:
+		return false
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, cmdPath, "-hide_banner", "-encoders").Output() // #nosec
+	if err != nil {
+		log.Warn(ctx, "Could not probe ffmpeg encoders; will retry on next animated cover", err)
+		return false
+	}
+
+	if parseEncodersOutput(out, encoder) {
+		p.state = encoderProbeAvailable
+		return true
+	}
+
+	p.state = encoderProbeUnavailable
+	log.Warn(ctx, "ffmpeg has no libwebp_anim encoder; animated covers will be served as static images",
+		"path", cmdPath, "hint", "install ffmpeg built with libwebp (e.g. `brew install ffmpeg@7`)")
+	return false
+}
+
 // These variables are accessible here for tests. Do not use them directly in production code. Use ffmpegCmd() instead.
 var (
 	ffOnce     sync.Once
 	ffmpegPath string
 	ffmpegErr  error
+	probeOnce  sync.Once
+	probeAvail bool
+	animWebP   encoderProbe
 )

core/ffmpeg/ffmpeg_test.go

@@ -3,8 +3,10 @@ package ffmpeg
 import (
 	"context"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"runtime"
+	"strings"
 	sync "sync"
 	"testing"
 	"time"
@@ -693,4 +695,57 @@ var _ = Describe("ffmpeg", func() {
 			})
 		})
 	})
+
+	Describe("parseEncodersOutput", func() {
+		const sample = `Encoders:
+ V..... = Video
+ ------
+ V....D apng                 APNG (Animated Portable Network Graphics) image
+ V....D libwebp_anim         libwebp WebP image (codec webp)
+ V....D libwebp              libwebp WebP image (codec webp)
+ A....D aac                  AAC (Advanced Audio Coding)
+`
+		It("returns true when the encoder is present", func() {
+			Expect(parseEncodersOutput([]byte(sample), "libwebp_anim")).To(BeTrue())
+			Expect(parseEncodersOutput([]byte(sample), "libwebp")).To(BeTrue())
+			Expect(parseEncodersOutput([]byte(sample), "aac")).To(BeTrue())
+		})
+		It("returns false when the encoder is absent", func() {
+			Expect(parseEncodersOutput([]byte(sample), "libwebp_missing")).To(BeFalse())
+			Expect(parseEncodersOutput([]byte(sample), "")).To(BeFalse())
+		})
+		It("does not match partial names", func() {
+			// libwebp is a prefix of libwebp_anim; the parser must treat names as whole-word.
+			stripped := `Encoders:
+ V....D libwebp              libwebp WebP image (codec webp)
+`
+			Expect(parseEncodersOutput([]byte(stripped), "libwebp_anim")).To(BeFalse())
+		})
+		It("handles empty output", func() {
+			Expect(parseEncodersOutput(nil, "libwebp_anim")).To(BeFalse())
+			Expect(parseEncodersOutput([]byte(""), "libwebp_anim")).To(BeFalse())
+		})
+	})
+
+	Describe("ConvertAnimatedImage", func() {
+		// Point ffmpegCmd at a stand-in binary that produces empty `-encoders`
+		// output so hasAnimatedWebPEncoder returns false. /usr/bin/true is
+		// portable across POSIX systems.
+		It("returns ErrAnimatedWebPUnsupported when the binary lacks libwebp_anim", func() {
+			truePath, err := exec.LookPath("true")
+			if err != nil {
+				Skip("true(1) not available")
+			}
+			origPath, origErr := ffmpegPath, ffmpegErr
+			ffmpegPath = truePath
+			ffmpegErr = nil
+			defer func() {
+				ffmpegPath, ffmpegErr = origPath, origErr
+			}()
+
+			ff := &ffmpeg{}
+			_, err = ff.ConvertAnimatedImage(GinkgoT().Context(), strings.NewReader("x"), 100, 75)
+			Expect(err).To(MatchError(ErrAnimatedWebPUnsupported))
+		})
+	})
 })

core/lyrics/lyrics_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/lyrics"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	"github.com/navidrome/navidrome/utils"
 	"github.com/navidrome/navidrome/utils/gg"
 	. "github.com/onsi/ginkgo/v2"
@@ -93,6 +94,7 @@ var _ = Describe("sources", func() {
 			var accessForbiddenFile string
 
 			BeforeEach(func() {
+				tests.SkipOnWindows("uses Unix file permission bits")
 				accessForbiddenFile = utils.TempFileName("access_forbidden-", ".mp3")
 
 				f, err := os.OpenFile(accessForbiddenFile, os.O_WRONLY|os.O_CREATE, 0222)

core/matcher/matcher.go

@@ -1,4 +1,4 @@
-package external
+package matcher
 
 import (
 	"context"
@@ -13,7 +13,17 @@ import (
 	"github.com/xrash/smetrics"
 )
 
-// matchSongsToLibrary matches agent song results to local library tracks using a multi-phase
+// Matcher matches agent song results to local library tracks.
+type Matcher struct {
+	ds model.DataStore
+}
+
+// New creates a new Matcher with the given DataStore.
+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.
 //
 // # Algorithm Overview
@@ -36,18 +46,20 @@ import (
 // # Fuzzy Matching Details
 //
 // For title+artist matching, the algorithm uses Jaro-Winkler similarity (threshold configurable
-// via SimilarSongsMatchThreshold, default 85%). Matches are ranked by:
+// 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. Specificity level (0-5, based on metadata precision):
+//  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
-//  4. Album similarity (Jaro-Winkler, as final tiebreaker)
+//  5. Album similarity (Jaro-Winkler, as final tiebreaker)
 //
 // # Examples
 //
@@ -95,36 +107,67 @@ import (
 //
 // 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.
-func (e *provider) matchSongsToLibrary(ctx context.Context, songs []agents.Song, count int) (model.MediaFiles, error) {
-	idMatches, err := e.loadTracksByID(ctx, songs)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by ID: %w", err)
-	}
-	mbidMatches, err := e.loadTracksByMBID(ctx, songs, idMatches)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by MBID: %w", err)
-	}
-	isrcMatches, err := e.loadTracksByISRC(ctx, songs, idMatches, mbidMatches)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by ISRC: %w", err)
-	}
-	titleMatches, err := e.loadTracksByTitleAndArtist(ctx, songs, idMatches, mbidMatches, isrcMatches)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by title: %w", err)
+func (m *Matcher) MatchSongs(ctx context.Context, songs []agents.Song, count int) (model.MediaFiles, error) {
+	if len(songs) == 0 {
+		return nil, nil
 	}
 
-	return e.selectBestMatchingSongs(songs, idMatches, mbidMatches, isrcMatches, titleMatches, count), nil
+	byID, byMBID, byISRC, byTitle, err := m.loadAllMatches(ctx, songs)
+	if err != nil {
+		return nil, err
+	}
+	return m.selectBestMatchingSongs(songs, byID, byMBID, byISRC, byTitle, 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.
+func (m *Matcher) MatchSongsIndexed(ctx context.Context, songs []agents.Song) (map[int]model.MediaFile, error) {
+	if len(songs) == 0 {
+		return nil, nil
+	}
+
+	byID, byMBID, byISRC, byTitle, err := m.loadAllMatches(ctx, songs)
+	if err != nil {
+		return nil, err
+	}
+
+	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
+		}
+	}
+	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.
-// It checks the song's ID, MBID, and ISRC fields against the corresponding map keys.
 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.
-// Returns the first matching MediaFile found and true, or an empty MediaFile and false if no match.
 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 {
@@ -140,10 +183,7 @@ func lookupByIdentifiers(s agents.Song, maps ...map[string]model.MediaFile) (mod
 }
 
 // loadTracksByID fetches MediaFiles from the library using direct ID matching.
-// It extracts all non-empty ID fields from the input songs and performs a single
-// batch query to the database. Returns a map keyed by MediaFile ID for O(1) lookup.
-// Only non-missing files are returned.
-func (e *provider) loadTracksByID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
+func (m *Matcher) loadTracksByID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
 	var ids []string
 	for _, s := range songs {
 		if s.ID != "" {
@@ -154,7 +194,7 @@ func (e *provider) loadTracksByID(ctx context.Context, songs []agents.Song) (map
 	if len(ids) == 0 {
 		return matches, nil
 	}
-	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	res, err := m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
 		Filters: squirrel.And{
 			squirrel.Eq{"media_file.id": ids},
 			squirrel.Eq{"missing": false},
@@ -172,10 +212,7 @@ func (e *provider) loadTracksByID(ctx context.Context, songs []agents.Song) (map
 }
 
 // loadTracksByMBID fetches MediaFiles from the library using MusicBrainz Recording IDs.
-// It extracts all non-empty MBID fields from the input songs and performs a single
-// batch query against the mbz_recording_id column. Returns a map keyed by MBID for
-// O(1) lookup. Only non-missing files are returned.
-func (e *provider) loadTracksByMBID(ctx context.Context, songs []agents.Song, priorMatches ...map[string]model.MediaFile) (map[string]model.MediaFile, error) {
+func (m *Matcher) loadTracksByMBID(ctx context.Context, songs []agents.Song, priorMatches ...map[string]model.MediaFile) (map[string]model.MediaFile, error) {
 	var mbids []string
 	for _, s := range songs {
 		if s.MBID != "" && !songMatchedIn(s, priorMatches...) {
@@ -186,7 +223,7 @@ func (e *provider) loadTracksByMBID(ctx context.Context, songs []agents.Song, pr
 	if len(mbids) == 0 {
 		return matches, nil
 	}
-	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	res, err := m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
 		Filters: squirrel.And{
 			squirrel.Eq{"mbz_recording_id": mbids},
 			squirrel.Eq{"missing": false},
@@ -205,11 +242,8 @@ func (e *provider) loadTracksByMBID(ctx context.Context, songs []agents.Song, pr
 	return matches, nil
 }
 
-// loadTracksByISRC fetches MediaFiles from the library using ISRC (International Standard
-// Recording Code) matching. It extracts all non-empty ISRC fields from the input songs and
-// queries the tags JSON column for matching ISRC values. Returns a map keyed by ISRC for
-// O(1) lookup. Only non-missing files are returned.
-func (e *provider) loadTracksByISRC(ctx context.Context, songs []agents.Song, priorMatches ...map[string]model.MediaFile) (map[string]model.MediaFile, error) {
+// 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) {
 	var isrcs []string
 	for _, s := range songs {
 		if s.ISRC != "" && !songMatchedIn(s, priorMatches...) {
@@ -220,8 +254,9 @@ func (e *provider) loadTracksByISRC(ctx context.Context, songs []agents.Song, pr
 	if len(isrcs) == 0 {
 		return matches, nil
 	}
-	res, err := e.ds.MediaFile(ctx).GetAllByTags(model.TagISRC, isrcs, model.QueryOptions{
+	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
@@ -237,27 +272,25 @@ func (e *provider) loadTracksByISRC(ctx context.Context, songs []agents.Song, pr
 }
 
 // songQuery represents a normalized query for matching a song to library tracks.
-// All string fields are sanitized (lowercased, diacritics removed) for comparison.
-// This struct is used internally by loadTracksByTitleAndArtist to group queries by artist.
 type songQuery struct {
-	title      string // Sanitized song title
-	artist     string // Sanitized artist name (without articles like "The")
-	artistMBID string // MusicBrainz Artist ID (optional, for higher specificity matching)
-	album      string // Sanitized album name (optional, for specificity scoring)
-	albumMBID  string // MusicBrainz Album ID (optional, for highest specificity matching)
-	durationMs uint32 // Duration in milliseconds (0 means unknown, skip duration filtering)
+	title      string
+	artist     string
+	artistMBID string
+	album      string
+	albumMBID  string
+	durationMs uint32
 }
 
-// matchScore combines title/album similarity with metadata specificity for ranking matches
+// matchScore combines title/album similarity with metadata specificity for ranking matches.
 type matchScore struct {
-	titleSimilarity   float64 // 0.0-1.0 (Jaro-Winkler)
-	durationProximity float64 // 0.0-1.0 (closer duration = higher, 1.0 if unknown)
-	albumSimilarity   float64 // 0.0-1.0 (Jaro-Winkler), used as tiebreaker
-	specificityLevel  int     // 0-5 (higher = more specific metadata match)
+	titleSimilarity   float64
+	durationProximity float64
+	preferredMatch    bool
+	albumSimilarity   float64
+	specificityLevel  int
 }
 
 // betterThan returns true if this score beats another.
-// Comparison order: title similarity > duration proximity > specificity level > album similarity
 func (s matchScore) betterThan(other matchScore) bool {
 	if s.titleSimilarity != other.titleSimilarity {
 		return s.titleSimilarity > other.titleSimilarity
@@ -265,64 +298,71 @@ func (s matchScore) betterThan(other matchScore) bool {
 	if s.durationProximity != other.durationProximity {
 		return s.durationProximity > other.durationProximity
 	}
+	if s.preferredMatch != other.preferredMatch {
+		return s.preferredMatch
+	}
 	if s.specificityLevel != other.specificityLevel {
 		return s.specificityLevel > other.specificityLevel
 	}
 	return s.albumSimilarity > other.albumSimilarity
 }
 
-// computeSpecificityLevel determines how well query metadata matches a track (0-5).
-// Higher values indicate more specific matches (MBIDs > names > title only).
-// Uses fuzzy matching for album names with the same threshold as title matching.
-func computeSpecificityLevel(q songQuery, mf model.MediaFile, albumThreshold float64) int {
-	title := str.SanitizeFieldForSorting(mf.Title)
-	artist := str.SanitizeFieldForSortingNoArticle(mf.Artist)
-	album := str.SanitizeFieldForSorting(mf.Album)
+// 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.
+type sanitizedTrack struct {
+	mf     *model.MediaFile
+	title  string
+	artist string
+	album  string
+}
 
-	// Level 5: Title + Artist MBID + Album MBID (most specific)
+func newSanitizedTrack(mf *model.MediaFile) sanitizedTrack {
+	return sanitizedTrack{
+		mf:     mf,
+		title:  str.SanitizeFieldForSorting(mf.Title),
+		artist: str.SanitizeFieldForSortingNoArticle(mf.Artist),
+		album:  str.SanitizeFieldForSorting(mf.Album),
+	}
+}
+
+// computeSpecificityLevel determines how well query metadata matches a track (0-5).
+// The track's title, artist, and album fields must be pre-sanitized.
+func computeSpecificityLevel(q songQuery, t sanitizedTrack, albumThreshold float64) int {
 	if q.artistMBID != "" && q.albumMBID != "" &&
-		mf.MbzArtistID == q.artistMBID && mf.MbzAlbumID == q.albumMBID {
+		t.mf.MbzArtistID == q.artistMBID && t.mf.MbzAlbumID == q.albumMBID {
 		return 5
 	}
-	// Level 4: Title + Artist MBID + Album name (fuzzy)
 	if q.artistMBID != "" && q.album != "" &&
-		mf.MbzArtistID == q.artistMBID && similarityRatio(album, q.album) >= albumThreshold {
+		t.mf.MbzArtistID == q.artistMBID && similarityRatio(t.album, q.album) >= albumThreshold {
 		return 4
 	}
-	// Level 3: Title + Artist name + Album name (fuzzy)
 	if q.artist != "" && q.album != "" &&
-		artist == q.artist && similarityRatio(album, q.album) >= albumThreshold {
+		t.artist == q.artist && similarityRatio(t.album, q.album) >= albumThreshold {
 		return 3
 	}
-	// Level 2: Title + Artist MBID
-	if q.artistMBID != "" && mf.MbzArtistID == q.artistMBID {
+	if q.artistMBID != "" && t.mf.MbzArtistID == q.artistMBID {
 		return 2
 	}
-	// Level 1: Title + Artist name
-	if q.artist != "" && artist == q.artist {
+	if q.artist != "" && t.artist == q.artist {
 		return 1
 	}
-	// Level 0: Title only match (but for fuzzy, title matched via similarity)
-	// Check if at least the title matches exactly
-	if title == q.title {
+	if t.title == q.title {
 		return 0
 	}
-	return -1 // No exact title match, but could still be a fuzzy match
+	return -1
 }
 
 // loadTracksByTitleAndArtist loads tracks matching by title with optional artist/album filtering.
-// Uses a unified scoring approach that combines title similarity (Jaro-Winkler) with
-// metadata specificity (MBIDs, album names) for both exact and fuzzy matches.
-// Returns a map keyed by "title|artist" for compatibility with selectBestMatchingSongs.
-func (e *provider) loadTracksByTitleAndArtist(ctx context.Context, songs []agents.Song, priorMatches ...map[string]model.MediaFile) (map[string]model.MediaFile, error) {
-	queries := e.buildTitleQueries(songs, priorMatches...)
+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
 	}
 
-	threshold := float64(conf.Server.SimilarSongsMatchThreshold) / 100.0
+	threshold := float64(conf.Server.Matcher.FuzzyThreshold) / 100.0
 
-	// Group queries by artist for efficient DB access
 	byArtist := map[string][]songQuery{}
 	for _, q := range queries {
 		if q.artist != "" {
@@ -332,8 +372,7 @@ func (e *provider) loadTracksByTitleAndArtist(ctx context.Context, songs []agent
 
 	matches := map[string]model.MediaFile{}
 	for artist, artistQueries := range byArtist {
-		// Single DB query per artist - get all their tracks
-		tracks, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		tracks, err := m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
 			Filters: squirrel.And{
 				squirrel.Eq{"order_artist_name": artist},
 				squirrel.Eq{"missing": false},
@@ -344,9 +383,13 @@ func (e *provider) loadTracksByTitleAndArtist(ctx context.Context, songs []agent
 			continue
 		}
 
-		// Find best match for each query using unified scoring
+		sanitized := make([]sanitizedTrack, len(tracks))
+		for i := range tracks {
+			sanitized[i] = newSanitizedTrack(&tracks[i])
+		}
+
 		for _, q := range artistQueries {
-			if mf, found := e.findBestMatch(q, tracks, threshold); found {
+			if mf, found := m.findBestMatch(q, sanitized, threshold); found {
 				key := q.title + "|" + q.artist
 				if _, exists := matches[key]; !exists {
 					matches[key] = mf
@@ -357,13 +400,11 @@ func (e *provider) loadTracksByTitleAndArtist(ctx context.Context, songs []agent
 	return matches, nil
 }
 
-// durationProximity returns a score from 0.0 to 1.0 indicating how close
-// the track's duration is to the target. A perfect match returns 1.0, and the
-// score decreases as the difference grows (using 1 / (1 + diff)). Returns 1.0
-// if durationMs is 0 (unknown), so duration does not influence scoring.
+// durationProximity returns a score from 0.0 to 1.0 indicating how close the track's duration
+// is to the target. Returns 1.0 if durationMs is 0 (unknown).
 func durationProximity(durationMs uint32, mediaFileDurationSec float32) float64 {
-	if durationMs <= 0 {
-		return 1.0 // Unknown duration — don't penalise
+	if durationMs == 0 {
+		return 1.0
 	}
 	durationSec := float64(durationMs) / 1000.0
 	diff := math.Abs(durationSec - float64(mediaFileDurationSec))
@@ -371,51 +412,46 @@ func durationProximity(durationMs uint32, mediaFileDurationSec float32) float64
 }
 
 // findBestMatch finds the best matching track using combined title/album similarity and specificity scoring.
-// A track must meet the threshold for title similarity, then the best match is chosen by:
-// 1. Highest title similarity
-// 2. Duration proximity (closer duration = higher score, 1.0 if unknown)
-// 3. Highest specificity level
-// 4. Highest album similarity (as final tiebreaker)
-func (e *provider) findBestMatch(q songQuery, tracks model.MediaFiles, threshold float64) (model.MediaFile, bool) {
+func (m *Matcher) findBestMatch(q songQuery, sanitizedTracks []sanitizedTrack, threshold float64) (model.MediaFile, bool) {
 	var bestMatch model.MediaFile
 	bestScore := matchScore{titleSimilarity: -1}
 	found := false
 
-	for _, mf := range tracks {
-		trackTitle := str.SanitizeFieldForSorting(mf.Title)
-		titleSim := similarityRatio(q.title, trackTitle)
+	for _, t := range sanitizedTracks {
+		titleSim := similarityRatio(q.title, t.title)
 
 		if titleSim < threshold {
 			continue
 		}
 
-		// Compute album similarity for tiebreaking (0.0 if no album in query)
 		var albumSim float64
 		if q.album != "" {
-			trackAlbum := str.SanitizeFieldForSorting(mf.Album)
-			albumSim = similarityRatio(q.album, trackAlbum)
+			albumSim = similarityRatio(q.album, t.album)
 		}
 
 		score := matchScore{
 			titleSimilarity:   titleSim,
-			durationProximity: durationProximity(q.durationMs, mf.Duration),
+			durationProximity: durationProximity(q.durationMs, t.mf.Duration),
+			preferredMatch:    conf.Server.Matcher.PreferStarred && isPreferredTrack(t.mf),
 			albumSimilarity:   albumSim,
-			specificityLevel:  computeSpecificityLevel(q, mf, threshold),
+			specificityLevel:  computeSpecificityLevel(q, t, threshold),
 		}
 
 		if score.betterThan(bestScore) {
 			bestScore = score
-			bestMatch = mf
+			bestMatch = *t.mf
 			found = true
 		}
 	}
 	return bestMatch, found
 }
 
+func isPreferredTrack(mf *model.MediaFile) bool {
+	return mf.Starred || mf.Rating >= 4
+}
+
 // buildTitleQueries converts agent songs into normalized songQuery structs for title+artist matching.
-// It skips songs that have already been matched in prior phases (by ID, MBID, or ISRC) and sanitizes
-// all string fields for consistent comparison (lowercase, diacritics removed, articles stripped from artist names).
-func (e *provider) buildTitleQueries(songs []agents.Song, priorMatches ...map[string]model.MediaFile) []songQuery {
+func (m *Matcher) buildTitleQueries(songs []agents.Song, priorMatches ...map[string]model.MediaFile) []songQuery {
 	var queries []songQuery
 	for _, s := range songs {
 		if songMatchedIn(s, priorMatches...) {
@@ -434,18 +470,9 @@ func (e *provider) buildTitleQueries(songs []agents.Song, priorMatches ...map[st
 }
 
 // selectBestMatchingSongs assembles the final result by mapping input songs to their best matching
-// library tracks. It iterates through the input songs in order and selects the first available match
-// using priority order: ID > MBID > ISRC > title+artist.
-//
-// The function also handles deduplication: when multiple different input songs would match the same
-// library track (e.g., "Song (Live)" and "Song (Remastered)" both matching "Song (Live)" in the library),
-// only the first match is kept. However, if the same input song appears multiple times (intentional
-// repetition), duplicates are preserved in the output.
-//
-// Returns up to 'count' MediaFiles, preserving the input order. Songs that cannot be matched are skipped.
-func (e *provider) selectBestMatchingSongs(songs []agents.Song, byID, byMBID, byISRC, byTitleArtist map[string]model.MediaFile, count int) model.MediaFiles {
+// 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 {
 	mfs := make(model.MediaFiles, 0, len(songs))
-	// Track MediaFile.ID -> input song that added it, for deduplication
 	addedBy := make(map[string]agents.Song, len(songs))
 
 	for _, t := range songs {
@@ -458,11 +485,9 @@ func (e *provider) selectBestMatchingSongs(songs []agents.Song, byID, byMBID, by
 			continue
 		}
 
-		// Check for duplicate library track
 		if prevSong, alreadyAdded := addedBy[mf.ID]; alreadyAdded {
-			// Only add duplicate if input songs are identical
 			if t != prevSong {
-				continue // Different input songs → skip mismatch-induced duplicate
+				continue
 			}
 		} else {
 			addedBy[mf.ID] = t
@@ -473,14 +498,11 @@ func (e *provider) selectBestMatchingSongs(songs []agents.Song, byID, byMBID, by
 	return mfs
 }
 
-// findMatchingTrack looks up a song in the match maps using priority order: ID > MBID > ISRC > title+artist.
-// Returns the matched MediaFile and true if found, or an empty MediaFile and false if no match exists.
+// 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) {
-	// Try identifier-based matches first (ID, MBID, ISRC)
 	if mf, found := lookupByIdentifiers(t, byID, byMBID, byISRC); found {
 		return mf, true
 	}
-	// Fall back to title+artist fuzzy match
 	key := str.SanitizeFieldForSorting(t.Name) + "|" + str.SanitizeFieldForSortingNoArticle(t.Artist)
 	if mf, ok := byTitleArtist[key]; ok {
 		return mf, true
@@ -489,9 +511,6 @@ func findMatchingTrack(t agents.Song, byID, byMBID, byISRC, byTitleArtist map[st
 }
 
 // similarityRatio calculates the similarity between two strings using Jaro-Winkler algorithm.
-// Returns a value between 0.0 (completely different) and 1.0 (identical).
-// Jaro-Winkler is well-suited for matching song titles because it gives higher scores
-// when strings share a common prefix (e.g., "Song Title" vs "Song Title - Remastered").
 func similarityRatio(a, b string) float64 {
 	if a == b {
 		return 1.0
@@ -499,6 +518,5 @@ func similarityRatio(a, b string) float64 {
 	if len(a) == 0 || len(b) == 0 {
 		return 0.0
 	}
-	// JaroWinkler params: boostThreshold=0.7, prefixSize=4
 	return smetrics.JaroWinkler(a, b, 0.7, 4)
 }

core/matcher/matcher_internal_test.go

@@ -1,4 +1,4 @@
-package external
+package matcher
 
 import (
 	. "github.com/onsi/ginkgo/v2"
@@ -16,25 +16,21 @@ var _ = Describe("similarityRatio", func() {
 	})
 
 	It("returns high similarity for remastered suffix", func() {
-		// Jaro-Winkler gives ~0.92 for this case
 		ratio := similarityRatio("paranoid android", "paranoid android remastered")
 		Expect(ratio).To(BeNumerically(">=", 0.85))
 	})
 
 	It("returns high similarity for suffix additions like (Live)", func() {
-		// Jaro-Winkler gives ~0.96 for this case
 		ratio := similarityRatio("bohemian rhapsody", "bohemian rhapsody live")
 		Expect(ratio).To(BeNumerically(">=", 0.90))
 	})
 
 	It("returns high similarity for 'yesterday' variants (common prefix)", func() {
-		// Jaro-Winkler gives ~0.90 because of common prefix
 		ratio := similarityRatio("yesterday", "yesterday once more")
 		Expect(ratio).To(BeNumerically(">=", 0.85))
 	})
 
 	It("returns low similarity for same suffix", func() {
-		// Jaro-Winkler gives ~0.70 for this case
 		ratio := similarityRatio("postman (live)", "taxman (live)")
 		Expect(ratio).To(BeNumerically("<", 0.85))
 	})

core/matcher/matcher_suite_test.go

@@ -0,0 +1,17 @@
+package matcher_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestMatcher(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Matcher Suite")
+}

core/matcher/matcher_test.go

@@ -0,0 +1,897 @@
+package matcher_test
+
+import (
+	"context"
+	"errors"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/matcher"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/stretchr/testify/mock"
+)
+
+var _ = Describe("Matcher", func() {
+	var ds model.DataStore
+	var mediaFileRepo *mockMediaFileRepo
+	var ctx context.Context
+	var m *matcher.Matcher
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+		DeferCleanup(configtest.SetupConfig())
+		mediaFileRepo = newMockMediaFileRepo()
+		DeferCleanup(func() {
+			mediaFileRepo.AssertExpectations(GinkgoT())
+		})
+		ds = &tests.MockDataStore{
+			MockedMediaFile: mediaFileRepo,
+		}
+		m = matcher.New(ds)
+	})
+
+	// Per-phase expectation helpers. Each `expect*Phase` registers a .Once() expectation
+	// that will fail the suite via AssertExpectations if the phase is NOT called. Tests
+	// use these to deterministically verify which matching phases fire. Phases that may
+	// or may not fire should use the `allow*Phase` variants instead, which register
+	// .Maybe() fallbacks.
+	expectIDPhase := func(matches model.MediaFiles) {
+		mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInAnd("media_file.id"))).
+			Return(matches, nil).Once()
+	}
+	expectMBIDPhase := func(matches model.MediaFiles) {
+		mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInAnd("mbz_recording_id"))).
+			Return(matches, nil).Once()
+	}
+	expectISRCPhase := func(matches model.MediaFiles) {
+		mediaFileRepo.On("GetAll", mock.MatchedBy(matchFieldInEq("missing"))).
+			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() {
+		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"))).
+			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()
+	}
+
+	Describe("MatchSongs", func() {
+		Context("matching by direct ID", func() {
+			It("matches songs with an ID field to MediaFiles by ID", func() {
+				conf.Server.Matcher.FuzzyThreshold = 100
+				songs := []agents.Song{
+					{ID: "track-1", Name: "Some Song", Artist: "Some Artist"},
+				}
+				idMatch := model.MediaFile{
+					ID: "track-1", Title: "Some Song", Artist: "Some Artist",
+				}
+				expectIDPhase(model.MediaFiles{idMatch})
+				allowOtherPhases()
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("track-1"))
+			})
+		})
+
+		Context("matching by MBID", func() {
+			It("matches songs with MBID to tracks with matching mbz_recording_id", func() {
+				conf.Server.Matcher.FuzzyThreshold = 100
+				songs := []agents.Song{
+					{Name: "Paranoid Android", MBID: "abc-123", Artist: "Radiohead"},
+				}
+				mbidMatch := model.MediaFile{
+					ID: "track-mbid", Title: "Paranoid Android", Artist: "Radiohead",
+					MbzRecordingID: "abc-123",
+				}
+				expectMBIDPhase(model.MediaFiles{mbidMatch})
+				allowOtherPhases()
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("track-mbid"))
+			})
+		})
+
+		Context("matching by ISRC", func() {
+			It("matches songs with ISRC to tracks with matching ISRC tag", func() {
+				conf.Server.Matcher.FuzzyThreshold = 100
+				songs := []agents.Song{
+					{Name: "Paranoid Android", ISRC: "GBAYE0000351", Artist: "Radiohead"},
+				}
+				isrcMatch := model.MediaFile{
+					ID: "track-isrc", Title: "Paranoid Android", Artist: "Radiohead",
+					Tags: model.Tags{model.TagISRC: []string{"GBAYE0000351"}},
+				}
+				expectISRCPhase(model.MediaFiles{isrcMatch})
+				allowOtherPhases()
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("track-isrc"))
+			})
+		})
+
+		Context("fuzzy title+artist matching", func() {
+			It("matches songs by title and artist name", func() {
+				conf.Server.Matcher.FuzzyThreshold = 100
+				songs := []agents.Song{
+					{Name: "Enjoy the Silence", Artist: "Depeche Mode"},
+				}
+				titleMatch := model.MediaFile{
+					ID: "track-title", Title: "Enjoy the Silence", Artist: "Depeche Mode",
+				}
+				setupTitleOnlyExpectations(model.MediaFiles{titleMatch})
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("track-title"))
+			})
+
+			It("matches songs with fuzzy title similarity", func() {
+				conf.Server.Matcher.FuzzyThreshold = 85
+				songs := []agents.Song{
+					{Name: "Bohemian Rhapsody", Artist: "Queen"},
+				}
+				fuzzyMatch := model.MediaFile{
+					ID: "track-fuzzy", Title: "Bohemian Rhapsody (Live)", Artist: "Queen",
+				}
+				setupTitleOnlyExpectations(model.MediaFiles{fuzzyMatch})
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("track-fuzzy"))
+			})
+
+			It("does not match completely different titles", func() {
+				conf.Server.Matcher.FuzzyThreshold = 85
+				songs := []agents.Song{
+					{Name: "Yesterday", Artist: "The Beatles"},
+				}
+				differentTracks := model.MediaFiles{
+					{ID: "different", Title: "Tomorrow Never Knows", Artist: "The Beatles"},
+				}
+				setupTitleOnlyExpectations(differentTracks)
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(BeEmpty())
+			})
+		})
+
+		Context("deduplication", func() {
+			It("removes duplicates when different input songs match the same library track", func() {
+				conf.Server.Matcher.FuzzyThreshold = 85
+				songs := []agents.Song{
+					{Name: "Bohemian Rhapsody (Live)", Artist: "Queen"},
+					{Name: "Bohemian Rhapsody (Original Mix)", Artist: "Queen"},
+				}
+				libraryTrack := model.MediaFile{
+					ID: "br-live", Title: "Bohemian Rhapsody (Live)", Artist: "Queen",
+				}
+				setupTitleOnlyExpectations(model.MediaFiles{libraryTrack})
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("br-live"))
+			})
+
+			It("preserves duplicates when identical input songs match the same library track", func() {
+				conf.Server.Matcher.FuzzyThreshold = 85
+				songs := []agents.Song{
+					{Name: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera"},
+					{Name: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera"},
+				}
+				libraryTrack := model.MediaFile{
+					ID: "br", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera",
+				}
+				setupTitleOnlyExpectations(model.MediaFiles{libraryTrack})
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(2))
+				Expect(result[0].ID).To(Equal("br"))
+				Expect(result[1].ID).To(Equal("br"))
+			})
+		})
+
+		Context("priority ordering", func() {
+			It("prefers ID match over MBID match", func() {
+				conf.Server.Matcher.FuzzyThreshold = 100
+				// Song has both ID and MBID set. The matcher should resolve via ID
+				// and short-circuit the MBID phase entirely, so no MBID fetch should
+				// occur even though an mbz_recording_id exists in the input.
+				songs := []agents.Song{
+					{ID: "track-id", Name: "Song", MBID: "mbid-1", Artist: "Artist"},
+				}
+				idMatch := model.MediaFile{
+					ID: "track-id", Title: "Song", Artist: "Artist",
+				}
+				expectIDPhase(model.MediaFiles{idMatch})
+				allowOtherPhases()
+				result, err := m.MatchSongs(ctx, songs, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("track-id"))
+			})
+		})
+
+		Context("count limit", func() {
+			It("returns at most 'count' results", func() {
+				conf.Server.Matcher.FuzzyThreshold = 100
+				songs := []agents.Song{
+					{Name: "Song A", Artist: "Artist"},
+					{Name: "Song B", Artist: "Artist"},
+					{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"},
+				}
+				setupTitleOnlyExpectations(tracks)
+				result, err := m.MatchSongs(ctx, songs, 2)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(2))
+			})
+		})
+
+		Context("empty input", func() {
+			It("returns empty results for no songs", func() {
+				result, err := m.MatchSongs(ctx, []agents.Song{}, 5)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(BeEmpty())
+			})
+		})
+	})
+
+	Describe("MatchSongsIndexed", func() {
+		It("returns index-keyed map of matched songs", func() {
+			songs := []agents.Song{
+				{ID: "track-1", Name: "Song One", Artist: "Artist A"},
+				{ID: "track-2", Name: "Song Two", Artist: "Artist B"},
+				{ID: "track-3", Name: "Song Three", Artist: "Artist C"},
+			}
+			mf1 := model.MediaFile{ID: "track-1", Title: "Song One", Artist: "Artist A"}
+			mf2 := model.MediaFile{ID: "track-2", Title: "Song Two", Artist: "Artist B"}
+
+			expectIDPhase(model.MediaFiles{mf1, mf2})
+			allowOtherPhases()
+
+			result, err := m.MatchSongsIndexed(ctx, songs)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(2))
+			Expect(result[0].ID).To(Equal("track-1"))
+			Expect(result[1].ID).To(Equal("track-2"))
+			_, exists := result[2]
+			Expect(exists).To(BeFalse())
+		})
+
+		It("preserves original indices when some songs don't match", func() {
+			songs := []agents.Song{
+				{Name: "Unknown Song", Artist: "Unknown Artist"},
+				{ID: "track-1", Name: "Known Song", Artist: "Known Artist"},
+			}
+			mf1 := model.MediaFile{ID: "track-1", Title: "Known Song", Artist: "Known Artist"}
+
+			expectIDPhase(model.MediaFiles{mf1})
+			allowOtherPhases()
+
+			result, err := m.MatchSongsIndexed(ctx, songs)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			_, exists := result[0]
+			Expect(exists).To(BeFalse())
+			Expect(result[1].ID).To(Equal("track-1"))
+		})
+
+		It("returns empty map for empty input", func() {
+			result, err := m.MatchSongsIndexed(ctx, nil)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(BeEmpty())
+		})
+	})
+
+	Describe("specificity level matching", func() {
+		BeforeEach(func() {
+			conf.Server.Matcher.FuzzyThreshold = 100
+		})
+
+		It("matches by title + artist MBID + album MBID (highest priority)", func() {
+			correctMatch := model.MediaFile{
+				ID: "correct-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Violator",
+				MbzArtistID: "artist-mbid-123", MbzAlbumID: "album-mbid-456",
+			}
+			wrongMatch := model.MediaFile{
+				ID: "wrong-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Some Other Album",
+				MbzArtistID: "artist-mbid-123", MbzAlbumID: "different-album-mbid",
+			}
+			songs := []agents.Song{
+				{Name: "Similar Song", Artist: "Depeche Mode", ArtistMBID: "artist-mbid-123", Album: "Violator", AlbumMBID: "album-mbid-456"},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("correct-match"))
+		})
+
+		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",
+			}
+			wrongMatch := model.MediaFile{
+				ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
+			}
+			songs := []agents.Song{
+				{Name: "Similar Song", Artist: "Depeche Mode", Album: "Violator"},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("correct-match"))
+		})
+
+		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",
+			}
+			wrongMatch := model.MediaFile{
+				ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
+			}
+			songs := []agents.Song{
+				{Name: "Similar Song", Artist: "Depeche Mode"},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("correct-match"))
+		})
+
+		It("does not match songs without artist info", func() {
+			songs := []agents.Song{
+				{Name: "Similar Song"},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(BeEmpty())
+		})
+
+		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"}
+
+			songs := []agents.Song{
+				{Name: "Yesterday", Artist: "The Beatles", Album: "Help!"},
+				{Name: "Yesterday", Artist: "Ray Charles", Album: "Greatest Hits"},
+				{Name: "Yesterday", Artist: "Frank Sinatra", Album: "My Way"},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{cover1, cover2, cover3})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(3))
+			ids := []string{result[0].ID, result[1].ID, result[2].ID}
+			Expect(ids).To(ContainElements("cover-1", "cover-2", "cover-3"))
+		})
+
+		It("prefers more precise matches for each song", func() {
+			preciseMatch := model.MediaFile{
+				ID: "precise", Title: "Song A", Artist: "Artist One", Album: "Album One",
+				MbzArtistID: "mbid-1", MbzAlbumID: "album-mbid-1",
+			}
+			lessAccurateMatch := model.MediaFile{
+				ID: "less-accurate", Title: "Song A", Artist: "Artist One", Album: "Compilation",
+				MbzArtistID: "mbid-1",
+			}
+			artistTwoMatch := model.MediaFile{
+				ID: "artist-two", Title: "Song B", Artist: "Artist Two",
+			}
+
+			songs := []agents.Song{
+				{Name: "Song A", Artist: "Artist One", ArtistMBID: "mbid-1", Album: "Album One", AlbumMBID: "album-mbid-1"},
+				{Name: "Song B", Artist: "Artist Two"},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{lessAccurateMatch, preciseMatch, artistTwoMatch})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(2))
+			Expect(result[0].ID).To(Equal("precise"))
+			Expect(result[1].ID).To(Equal("artist-two"))
+		})
+	})
+
+	Describe("fuzzy matching thresholds", func() {
+		Context("with default threshold (85%)", func() {
+			It("matches songs with remastered suffix", func() {
+				conf.Server.Matcher.FuzzyThreshold = 85
+
+				songs := []agents.Song{
+					{Name: "Paranoid Android", Artist: "Radiohead"},
+				}
+				artistTracks := model.MediaFiles{
+					{ID: "remastered", Title: "Paranoid Android - Remastered", Artist: "Radiohead"},
+				}
+
+				setupTitleOnlyExpectations(artistTracks)
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("remastered"))
+			})
+
+			It("matches songs with live suffix", func() {
+				conf.Server.Matcher.FuzzyThreshold = 85
+
+				songs := []agents.Song{
+					{Name: "Bohemian Rhapsody", Artist: "Queen"},
+				}
+				artistTracks := model.MediaFiles{
+					{ID: "live", Title: "Bohemian Rhapsody (Live)", Artist: "Queen"},
+				}
+
+				setupTitleOnlyExpectations(artistTracks)
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("live"))
+			})
+		})
+
+		Context("with threshold set to 100 (exact match only)", func() {
+			It("only matches exact titles", func() {
+				conf.Server.Matcher.FuzzyThreshold = 100
+
+				songs := []agents.Song{
+					{Name: "Paranoid Android", Artist: "Radiohead"},
+				}
+				artistTracks := model.MediaFiles{
+					{ID: "remastered", Title: "Paranoid Android - Remastered", Artist: "Radiohead"},
+				}
+
+				setupTitleOnlyExpectations(artistTracks)
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(BeEmpty())
+			})
+		})
+
+		Context("with lower threshold (75%)", func() {
+			It("matches more aggressively", func() {
+				conf.Server.Matcher.FuzzyThreshold = 75
+
+				songs := []agents.Song{
+					{Name: "Song", Artist: "Artist"},
+				}
+				artistTracks := model.MediaFiles{
+					{ID: "extended", Title: "Song (Extended Mix)", Artist: "Artist"},
+				}
+
+				setupTitleOnlyExpectations(artistTracks)
+
+				result, err := m.MatchSongs(ctx, songs, 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(result).To(HaveLen(1))
+				Expect(result[0].ID).To(Equal("extended"))
+			})
+		})
+	})
+
+	Describe("fuzzy album matching", func() {
+		BeforeEach(func() {
+			conf.Server.Matcher.FuzzyThreshold = 85
+			conf.Server.Matcher.PreferStarred = false
+		})
+
+		It("matches album with (Remaster) suffix", func() {
+			songs := []agents.Song{
+				{Name: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera"},
+			}
+			correctMatch := model.MediaFile{
+				ID: "correct", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera (2011 Remaster)",
+			}
+			wrongMatch := model.MediaFile{
+				ID: "wrong", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "Greatest Hits",
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("correct"))
+		})
+
+		It("matches album with (Deluxe Edition) suffix", func() {
+			songs := []agents.Song{
+				{Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"},
+			}
+			correctMatch := model.MediaFile{
+				ID: "correct", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator (Deluxe Edition)",
+			}
+			wrongMatch := model.MediaFile{
+				ID: "wrong", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "101",
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("correct"))
+		})
+
+		It("prefers exact album match over fuzzy album match", func() {
+			songs := []agents.Song{
+				{Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"},
+			}
+			exactMatch := model.MediaFile{
+				ID: "exact", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator",
+			}
+			fuzzyMatch := model.MediaFile{
+				ID: "fuzzy", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator (Deluxe Edition)",
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{fuzzyMatch, exactMatch})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("exact"))
+		})
+
+		It("prefers starred songs over better album match when enabled", func() {
+			conf.Server.Matcher.PreferStarred = true
+			songs := []agents.Song{
+				{Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"},
+			}
+			albumMatch := model.MediaFile{
+				ID: "album-match", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator",
+			}
+			starredTrack := model.MediaFile{
+				ID: "starred", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles", Annotations: model.Annotations{Starred: true},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{albumMatch, starredTrack})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("starred"))
+		})
+
+		It("prefers 4-star songs over better album match when enabled", func() {
+			conf.Server.Matcher.PreferStarred = true
+			songs := []agents.Song{
+				{Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"},
+			}
+			albumMatch := model.MediaFile{
+				ID: "album-match", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator",
+			}
+			ratedTrack := model.MediaFile{
+				ID: "rated", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles", Annotations: model.Annotations{Rating: 4},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{albumMatch, ratedTrack})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("rated"))
+		})
+	})
+
+	Describe("duration matching", func() {
+		BeforeEach(func() {
+			conf.Server.Matcher.FuzzyThreshold = 100
+		})
+
+		It("prefers tracks with matching duration", func() {
+			songs := []agents.Song{
+				{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
+			}
+			correctMatch := model.MediaFile{
+				ID: "correct", Title: "Similar Song", Artist: "Test Artist", Duration: 180.0,
+			}
+			wrongDuration := model.MediaFile{
+				ID: "wrong", Title: "Similar Song", Artist: "Test Artist", Duration: 240.0,
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{wrongDuration, correctMatch})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("correct"))
+		})
+
+		It("matches tracks with close duration", func() {
+			songs := []agents.Song{
+				{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
+			}
+			closeDuration := model.MediaFile{
+				ID: "close-duration", Title: "Similar Song", Artist: "Test Artist", Duration: 182.5,
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{closeDuration})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("close-duration"))
+		})
+
+		It("prefers closer duration over farther duration", func() {
+			songs := []agents.Song{
+				{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
+			}
+			closeDuration := model.MediaFile{
+				ID: "close", Title: "Similar Song", Artist: "Test Artist", Duration: 181.0,
+			}
+			farDuration := model.MediaFile{
+				ID: "far", Title: "Similar Song", Artist: "Test Artist", Duration: 190.0,
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{farDuration, closeDuration})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("close"))
+		})
+
+		It("still matches when no tracks have matching duration", func() {
+			songs := []agents.Song{
+				{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
+			}
+			differentDuration := model.MediaFile{
+				ID: "different", Title: "Similar Song", Artist: "Test Artist", Duration: 300.0,
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{differentDuration})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("different"))
+		})
+
+		It("prefers title match over duration match when titles differ", func() {
+			songs := []agents.Song{
+				{Name: "Similar Song", Artist: "Test Artist", Duration: 180000},
+			}
+			differentTitle := model.MediaFile{
+				ID: "wrong-title", Title: "Different Song", Artist: "Test Artist", Duration: 180.0,
+			}
+			correctTitle := model.MediaFile{
+				ID: "correct-title", Title: "Similar Song", Artist: "Test Artist", Duration: 300.0,
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{differentTitle, correctTitle})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("correct-title"))
+		})
+
+		It("matches without duration filtering when agent duration is 0", func() {
+			songs := []agents.Song{
+				{Name: "Similar Song", Artist: "Test Artist", Duration: 0},
+			}
+			anyTrack := model.MediaFile{
+				ID: "any", Title: "Similar Song", Artist: "Test Artist", Duration: 999.0,
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{anyTrack})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("any"))
+		})
+
+		It("handles very short songs with close duration", func() {
+			songs := []agents.Song{
+				{Name: "Short Song", Artist: "Test Artist", Duration: 30000},
+			}
+			shortTrack := model.MediaFile{
+				ID: "short", Title: "Short Song", Artist: "Test Artist", Duration: 31.0,
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{shortTrack})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("short"))
+		})
+	})
+
+	Describe("deduplication edge cases", func() {
+		BeforeEach(func() {
+			conf.Server.Matcher.FuzzyThreshold = 85
+		})
+
+		It("handles mixed scenario with both identical and different input songs", func() {
+			songs := []agents.Song{
+				{Name: "Yesterday", Artist: "The Beatles", Album: "Help!"},
+				{Name: "Yesterday (Remastered)", Artist: "The Beatles", Album: "1"},
+				{Name: "Yesterday", Artist: "The Beatles", Album: "Help!"},
+				{Name: "Yesterday (Anthology)", Artist: "The Beatles", Album: "Anthology"},
+			}
+			libraryTrack := model.MediaFile{
+				ID: "yesterday", Title: "Yesterday", Artist: "The Beatles", Album: "Help!",
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{libraryTrack})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(2))
+			Expect(result[0].ID).To(Equal("yesterday"))
+			Expect(result[1].ID).To(Equal("yesterday"))
+		})
+
+		It("does not deduplicate songs that match different library tracks", func() {
+			songs := []agents.Song{
+				{Name: "Song A", Artist: "Artist"},
+				{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"}
+
+			setupTitleOnlyExpectations(model.MediaFiles{trackA, trackB, trackC})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(3))
+			Expect(result[0].ID).To(Equal("track-a"))
+			Expect(result[1].ID).To(Equal("track-b"))
+			Expect(result[2].ID).To(Equal("track-c"))
+		})
+
+		It("respects count limit after deduplication", func() {
+			songs := []agents.Song{
+				{Name: "Song A", Artist: "Artist"},
+				{Name: "Song A (Live)", Artist: "Artist"},
+				{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"}
+
+			setupTitleOnlyExpectations(model.MediaFiles{trackA, trackB})
+
+			result, err := m.MatchSongs(ctx, songs, 2)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(2))
+			Expect(result[0].ID).To(Equal("track-a"))
+			Expect(result[1].ID).To(Equal("track-b"))
+		})
+	})
+})
+
+type mockMediaFileRepo struct {
+	mock.Mock
+	model.MediaFileRepository
+}
+
+func newMockMediaFileRepo() *mockMediaFileRepo {
+	return &mockMediaFileRepo{}
+}
+
+func (m *mockMediaFileRepo) GetAll(options ...model.QueryOptions) (model.MediaFiles, 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.MediaFiles), args.Error(1)
+}
+
+func (m *mockMediaFileRepo) GetAllByTags(_ model.TagName, _ []string, options ...model.QueryOptions) (model.MediaFiles, error) {
+	return m.GetAll(options...)
+}
+
+func (m *mockMediaFileRepo) SetError(hasError bool) {
+	if hasError {
+		m.On("GetAll", mock.Anything).Return(nil, errors.New("mock repo error"))
+	}
+}
+
+// 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 {
+	return func(opt model.QueryOptions) bool {
+		and, ok := opt.Filters.(squirrel.And)
+		if !ok || len(and) < 2 {
+			return false
+		}
+		eq, hasEq := and[0].(squirrel.Eq)
+		if !hasEq {
+			return false
+		}
+		_, hasField := eq[fieldName]
+		return hasField
+	}
+}
+
+// matchFieldInEq returns a matcher that checks whether QueryOptions.Filters is a
+// squirrel.Eq containing the given field name.
+func matchFieldInEq(fieldName string) func(opt model.QueryOptions) bool {
+	return func(opt model.QueryOptions) bool {
+		eq, ok := opt.Filters.(squirrel.Eq)
+		if !ok {
+			return false
+		}
+		_, hasField := eq[fieldName]
+		return hasField
+	}
+}

core/metrics/insights.go

@@ -195,6 +195,8 @@ var staticData = sync.OnceValue(func() insights.Data {
 	data.Config.EnableArtworkPrecache = conf.Server.EnableArtworkPrecache
 	data.Config.EnableArtworkUpload = conf.Server.EnableArtworkUpload
 	data.Config.CoverArtQuality = conf.Server.CoverArtQuality
+	data.Config.EnableWebPEncoding = conf.Server.EnableWebPEncoding
+	data.Config.UICoverArtSize = conf.Server.UICoverArtSize
 	data.Config.EnableCoverAnimation = conf.Server.EnableCoverAnimation
 	data.Config.EnableNowPlaying = conf.Server.EnableNowPlaying
 	data.Config.EnableDownloads = conf.Server.EnableDownloads

core/metrics/insights/data.go

@@ -65,6 +65,8 @@ type Data struct {
 		EnablePrometheus        bool   `json:"enablePrometheus,omitempty"`
 		EnableArtworkUpload     bool   `json:"enableArtworkUpload,omitempty"`
 		CoverArtQuality         int    `json:"coverArtQuality,omitempty"`
+		EnableWebPEncoding      bool   `json:"enableWebPEncoding,omitempty"`
+		UICoverArtSize          int    `json:"uiCoverArtSize,omitempty"`
 		EnableCoverAnimation    bool   `json:"enableCoverAnimation,omitempty"`
 		EnableNowPlaying        bool   `json:"enableNowPlaying,omitempty"`
 		SessionTimeout          uint64 `json:"sessionTimeout,omitempty"`

core/playback/mpv/mpv_test.go

@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -199,6 +200,7 @@ var _ = Describe("MPV", func() {
 		})
 
 		It("executes MPV command and captures arguments correctly", func() {
+			tests.SkipOnWindows("mpv binary not available in CI (#TBD-mpv-windows)")
 			ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
 
@@ -226,6 +228,7 @@ var _ = Describe("MPV", func() {
 		})
 
 		It("handles file paths with spaces", func() {
+			tests.SkipOnWindows("mpv binary not available in CI (#TBD-mpv-windows)")
 			ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
 
@@ -253,6 +256,7 @@ var _ = Describe("MPV", func() {
 			})
 
 			It("passes all snapcast arguments correctly", func() {
+				tests.SkipOnWindows("mpv binary not available in CI (#TBD-mpv-windows)")
 				ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 				defer cancel()
 

core/playlists/import.go

@@ -3,6 +3,7 @@ package playlists
 import (
 	"context"
 	"errors"
+	"fmt"
 	"io"
 	"os"
 	"path/filepath"
@@ -17,14 +18,89 @@ import (
 	"golang.org/x/text/unicode/norm"
 )
 
-func (s *playlists) ImportFile(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error) {
+func (s *playlists) ImportFile(ctx context.Context, absolutePath string, sync bool) (*model.Playlist, error) {
+	absPath, err := filepath.Abs(absolutePath)
+	if err != nil {
+		return nil, fmt.Errorf("resolving absolute path: %w", err)
+	}
+
+	dir := filepath.Dir(absPath)
+	filename := filepath.Base(absPath)
+
+	folder, err := s.resolveFolder(ctx, dir)
+	if err != nil && !errors.Is(err, errNotInLibrary) {
+		return nil, err
+	}
+	if err == nil {
+		pls, err := s.importFromFolder(ctx, folder, filename, sync)
+		if err != nil {
+			return nil, err
+		}
+		if pls.ID != "" && pls.Sync != sync {
+			pls.Sync = sync
+			if putErr := s.ds.Playlist(ctx).Put(pls); putErr != nil {
+				return nil, putErr
+			}
+		}
+		return pls, nil
+	}
+
+	log.Debug(ctx, "Playlist file is outside all libraries, using path-based import", "path", absPath)
+	pls, err := s.newSyncedPlaylist(dir, filename)
+	if err != nil {
+		return nil, fmt.Errorf("reading playlist file: %w", err)
+	}
+	pls.Sync = sync
+
+	file, err := os.Open(absPath)
+	if err != nil {
+		return nil, fmt.Errorf("opening playlist file: %w", err)
+	}
+	defer file.Close()
+
+	reader := ioutils.UTF8Reader(file)
+	if err := s.parseM3U(ctx, pls, nil, reader); err != nil {
+		return nil, err
+	}
+	if err := s.updatePlaylist(ctx, pls, sync); err != nil {
+		return nil, err
+	}
+	return pls, nil
+}
+
+var errNotInLibrary = fmt.Errorf("path not in any library")
+
+func (s *playlists) resolveFolder(ctx context.Context, dir string) (*model.Folder, error) {
+	libs, err := s.ds.Library(ctx).GetAll()
+	if err != nil {
+		return nil, err
+	}
+	matcher := newLibraryMatcher(libs)
+	lib, ok := matcher.findLibrary(dir)
+	if !ok {
+		return nil, fmt.Errorf("%w: %s", errNotInLibrary, dir)
+	}
+
+	folder, err := s.ds.Folder(ctx).GetByPath(lib, dir)
+	if err != nil {
+		return nil, fmt.Errorf("resolving folder for path %s: %w", dir, err)
+	}
+	folder.LibraryPath = lib.Path
+	return folder, nil
+}
+
+func (s *playlists) ImportFromFolder(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error) {
+	return s.importFromFolder(ctx, folder, filename, false)
+}
+
+func (s *playlists) importFromFolder(ctx context.Context, folder *model.Folder, filename string, forceSync bool) (*model.Playlist, error) {
 	pls, err := s.parsePlaylist(ctx, filename, folder)
 	if err != nil {
 		log.Error(ctx, "Error parsing playlist", "path", filepath.Join(folder.AbsolutePath(), filename), err)
 		return nil, err
 	}
 	log.Debug(ctx, "Found playlist", "name", pls.Name, "lastUpdated", pls.UpdatedAt, "path", pls.Path, "numTracks", len(pls.Tracks))
-	err = s.updatePlaylist(ctx, pls)
+	err = s.updatePlaylist(ctx, pls, forceSync)
 	if err != nil {
 		log.Error(ctx, "Error updating playlist", "path", filepath.Join(folder.AbsolutePath(), filename), err)
 	}
@@ -74,27 +150,31 @@ func (s *playlists) parsePlaylist(ctx context.Context, playlistFile string, fold
 	return pls, err
 }
 
-func (s *playlists) updatePlaylist(ctx context.Context, newPls *model.Playlist) error {
-	owner, _ := request.UserFrom(ctx)
-
-	// Try to find existing playlist by path. Since filesystem normalization differs across
-	// platforms (macOS uses NFD, Linux/Windows use NFC), we try both forms to match
-	// playlists that may have been imported on a different platform.
-	pls, err := s.ds.Playlist(ctx).FindByPath(newPls.Path)
+// findByPathNormalized looks up a playlist by path, trying both NFC and NFD Unicode
+// normalization forms to handle cross-platform filesystem differences.
+func (s *playlists) findByPathNormalized(ctx context.Context, path string) (*model.Playlist, error) {
+	pls, err := s.ds.Playlist(ctx).FindByPath(path)
 	if errors.Is(err, model.ErrNotFound) {
-		// Try alternate normalization form
-		altPath := norm.NFD.String(newPls.Path)
-		if altPath == newPls.Path {
-			altPath = norm.NFC.String(newPls.Path)
+		altPath := norm.NFD.String(path)
+		if altPath == path {
+			altPath = norm.NFC.String(path)
 		}
-		if altPath != newPls.Path {
+		if altPath != path {
 			pls, err = s.ds.Playlist(ctx).FindByPath(altPath)
 		}
 	}
+	return pls, err
+}
+
+func (s *playlists) updatePlaylist(ctx context.Context, newPls *model.Playlist, forceSync bool) error {
+	owner, _ := request.UserFrom(ctx)
+
+	pls, err := s.findByPathNormalized(ctx, newPls.Path)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		return err
 	}
-	if err == nil && !pls.Sync {
+	alreadyImportedAndNotSynced := err == nil && !pls.Sync && !forceSync
+	if alreadyImportedAndNotSynced {
 		log.Debug(ctx, "Playlist already imported and not synced", "playlist", pls.Name, "path", pls.Path)
 		return nil
 	}

core/playlists/import_test.go

@@ -39,7 +39,7 @@ var _ = Describe("Playlists - Import", func() {
 		ctx = request.WithUser(ctx, model.User{ID: "123"})
 	})
 
-	Describe("ImportFile", func() {
+	Describe("ImportFromFolder", func() {
 		var folder *model.Folder
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
@@ -59,7 +59,7 @@ var _ = Describe("Playlists - Import", func() {
 
 		Describe("M3U", func() {
 			It("parses well-formed playlists", func() {
-				pls, err := ps.ImportFile(ctx, folder, "pls1.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "pls1.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.OwnerID).To(Equal("123"))
 				Expect(pls.Tracks).To(HaveLen(2))
@@ -69,19 +69,19 @@ var _ = Describe("Playlists - Import", func() {
 			})
 
 			It("parses playlists using LF ending", func() {
-				pls, err := ps.ImportFile(ctx, folder, "lf-ended.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "lf-ended.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 			})
 
 			It("parses playlists using CR ending (old Mac format)", func() {
-				pls, err := ps.ImportFile(ctx, folder, "cr-ended.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "cr-ended.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 			})
 
 			It("parses playlists with UTF-8 BOM marker", func() {
-				pls, err := ps.ImportFile(ctx, folder, "bom-test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "bom-test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.OwnerID).To(Equal("123"))
 				Expect(pls.Name).To(Equal("Test Playlist"))
@@ -90,7 +90,7 @@ var _ = Describe("Playlists - Import", func() {
 			})
 
 			It("parses UTF-16 LE encoded playlists with BOM and converts to UTF-8", func() {
-				pls, err := ps.ImportFile(ctx, folder, "bom-test-utf16.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "bom-test-utf16.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.OwnerID).To(Equal("123"))
 				Expect(pls.Name).To(Equal("UTF-16 Test Playlist"))
@@ -101,7 +101,7 @@ var _ = Describe("Playlists - Import", func() {
 			It("parses #EXTALBUMARTURL with HTTP URL", func() {
 				conf.Server.EnableM3UExternalAlbumArt = true
 
-				pls, err := ps.ImportFile(ctx, folder, "pls-with-art-url.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "pls-with-art-url.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal("https://example.com/cover.jpg"))
 				Expect(pls.Tracks).To(HaveLen(2))
@@ -121,7 +121,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal(imgPath))
 			})
@@ -139,7 +139,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal(filepath.Join(tmpDir, "cover.jpg")))
 			})
@@ -158,7 +158,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal(imgPath))
 			})
@@ -177,12 +177,13 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal(imgPath))
 			})
 
 			It("rejects #EXTALBUMARTURL with absolute path outside library boundaries", func() {
+				tests.SkipOnWindows("relies on Unix /etc filesystem")
 				tmpDir := GinkgoT().TempDir()
 
 				m3u := "#EXTALBUMARTURL:/etc/passwd\ntest.mp3\n"
@@ -194,7 +195,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -211,7 +212,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -228,7 +229,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -246,7 +247,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -274,12 +275,38 @@ var _ = Describe("Playlists - Import", func() {
 				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.UploadedImage).To(Equal("existing-id.jpg"))
 				Expect(pls.ExternalImageURL).To(Equal("https://example.com/new-cover.jpg"))
 			})
 
+			It("skips non-synced playlist on re-import (respects user's choice)", func() {
+				tmpDir := GinkgoT().TempDir()
+				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
+				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+				plsFile := filepath.Join(tmpDir, "test.m3u")
+				Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
+
+				existingPls := &model.Playlist{
+					ID:      "existing-id",
+					Name:    "Existing Playlist",
+					Path:    plsFile,
+					Sync:    false,
+					OwnerID: "123",
+				}
+				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
+
+				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
+				Expect(err).ToNot(HaveOccurred())
+				// updatePlaylist skips the non-synced playlist, so the returned
+				// playlist has no ID (was never persisted/updated).
+				Expect(pls.ID).To(BeEmpty())
+			})
+
 			It("clears ExternalImageURL on re-scan when directive is removed", func() {
 				tmpDir := GinkgoT().TempDir()
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
@@ -300,7 +327,7 @@ var _ = Describe("Playlists - Import", func() {
 				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -308,7 +335,7 @@ var _ = Describe("Playlists - Import", func() {
 
 		Describe("NSP", func() {
 			It("parses well-formed playlists", func() {
-				pls, err := ps.ImportFile(ctx, folder, "recently_played.nsp")
+				pls, err := ps.ImportFromFolder(ctx, folder, "recently_played.nsp")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockPlsRepo.Last).To(Equal(pls))
 				Expect(pls.OwnerID).To(Equal("123"))
@@ -320,17 +347,18 @@ var _ = Describe("Playlists - Import", func() {
 				Expect(pls.Rules.Expression).To(BeAssignableToTypeOf(criteria.All{}))
 			})
 			It("returns an error if the playlist is not well-formed", func() {
-				_, err := ps.ImportFile(ctx, folder, "invalid_json.nsp")
+				tests.SkipOnWindows("line-ending differences affect JSON error offset")
+				_, err := ps.ImportFromFolder(ctx, folder, "invalid_json.nsp")
 				Expect(err.Error()).To(ContainSubstring("line 19, column 1: invalid character '\\n'"))
 			})
 			It("parses NSP with public: true and creates public playlist", func() {
-				pls, err := ps.ImportFile(ctx, folder, "public_playlist.nsp")
+				pls, err := ps.ImportFromFolder(ctx, folder, "public_playlist.nsp")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Name).To(Equal("Public Playlist"))
 				Expect(pls.Public).To(BeTrue())
 			})
 			It("parses NSP with public: false and creates private playlist", func() {
-				pls, err := ps.ImportFile(ctx, folder, "private_playlist.nsp")
+				pls, err := ps.ImportFromFolder(ctx, folder, "private_playlist.nsp")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Name).To(Equal("Private Playlist"))
 				Expect(pls.Public).To(BeFalse())
@@ -338,7 +366,7 @@ var _ = Describe("Playlists - Import", func() {
 			It("uses server default when public field is absent", func() {
 				conf.Server.DefaultPlaylistPublicVisibility = true
 
-				pls, err := ps.ImportFile(ctx, folder, "recently_played.nsp")
+				pls, err := ps.ImportFromFolder(ctx, folder, "recently_played.nsp")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Name).To(Equal("Recently Played"))
 				Expect(pls.Public).To(BeTrue()) // Should be true since server default is true
@@ -347,6 +375,7 @@ var _ = Describe("Playlists - Import", func() {
 
 		DescribeTable("Playlist filename Unicode normalization (regression fix-playlist-filename-normalization)",
 			func(storedForm, filesystemForm string) {
+				tests.SkipOnWindows("/tmp hardcoded in test")
 				// Use Polish characters that decompose: ó (U+00F3) -> o + combining acute (U+006F + U+0301)
 				plsNameNFC := "Piosenki_Polskie_zółć" // NFC form (composed)
 				plsNameNFD := norm.NFD.String(plsNameNFC)
@@ -383,7 +412,7 @@ var _ = Describe("Playlists - Import", func() {
 					Path:        "",
 					Name:        "",
 				}
-				pls, err := ps.ImportFile(ctx, plsFolder, filesystemName+".m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, filesystemName+".m3u")
 				Expect(err).ToNot(HaveOccurred())
 
 				// Should update existing playlist, not create new one
@@ -438,7 +467,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "",
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 				Expect(pls.Tracks[0].Path).To(Equal("abc.mp3")) // From songsDir library
@@ -459,7 +488,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "",
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				// Should only find abc.mp3, not outside.mp3
 				Expect(pls.Tracks).To(HaveLen(1))
@@ -496,7 +525,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "subfolder", // The folder name
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 				Expect(pls.Tracks[0].Path).To(Equal("abc.mp3")) // From songsDir library
@@ -539,7 +568,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "",
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 				Expect(pls.Tracks[0].Path).To(Equal("rock.mp3")) // From music library
@@ -590,7 +619,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "",
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 
 				// Should have BOTH tracks, not just one
@@ -613,6 +642,126 @@ var _ = Describe("Playlists - Import", func() {
 		})
 	})
 
+	Describe("ImportFile", func() {
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3", "test.ogg"}}
+		})
+
+		It("resolves file inside a library and imports it", func() {
+			tmpDir := GinkgoT().TempDir()
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+
+			mockFolderRepo := &mockFolderRepoForImport{
+				folder: &model.Folder{
+					ID:          "1",
+					LibraryID:   1,
+					LibraryPath: tmpDir,
+					Path:        "",
+					Name:        "",
+				},
+			}
+			ds.MockedFolder = mockFolderRepo
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsContent := "#PLAYLIST:My Playlist\ntest.mp3\ntest.ogg\n"
+			plsFile := filepath.Join(tmpDir, "my-playlist.m3u")
+			Expect(os.WriteFile(plsFile, []byte(plsContent), 0600)).To(Succeed())
+
+			pls, err := ps.ImportFile(ctx, plsFile, true)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.Name).To(Equal("My Playlist"))
+			Expect(pls.Tracks).To(HaveLen(2))
+			Expect(pls.Path).To(Equal(plsFile))
+			Expect(pls.Sync).To(BeTrue())
+		})
+
+		It("records path for files outside all libraries", func() {
+			tmpDir := GinkgoT().TempDir()
+			libDir := filepath.Join(tmpDir, "music")
+			Expect(os.Mkdir(libDir, 0755)).To(Succeed())
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: libDir}})
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsContent := "#PLAYLIST:External Playlist\n" + libDir + "/test.mp3\n"
+			plsFile := filepath.Join(tmpDir, "external.m3u")
+			Expect(os.WriteFile(plsFile, []byte(plsContent), 0600)).To(Succeed())
+
+			pls, err := ps.ImportFile(ctx, plsFile, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.Name).To(Equal("External Playlist"))
+			Expect(pls.Path).To(Equal(plsFile))
+			Expect(pls.Sync).To(BeFalse())
+		})
+
+		It("imports with Sync=false", func() {
+			tmpDir := GinkgoT().TempDir()
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+
+			mockFolderRepo := &mockFolderRepoForImport{
+				folder: &model.Folder{
+					ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: "",
+				},
+			}
+			ds.MockedFolder = mockFolderRepo
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsFile := filepath.Join(tmpDir, "test.m3u")
+			Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
+
+			pls, err := ps.ImportFile(ctx, plsFile, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.Sync).To(BeFalse())
+		})
+
+		It("imports with Sync=true", func() {
+			tmpDir := GinkgoT().TempDir()
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+
+			mockFolderRepo := &mockFolderRepoForImport{
+				folder: &model.Folder{
+					ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: "",
+				},
+			}
+			ds.MockedFolder = mockFolderRepo
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsFile := filepath.Join(tmpDir, "test.m3u")
+			Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
+
+			pls, err := ps.ImportFile(ctx, plsFile, true)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.Sync).To(BeTrue())
+		})
+
+		It("upgrades non-synced playlist to synced on re-import with sync=true", func() {
+			tmpDir := GinkgoT().TempDir()
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+
+			mockFolderRepo := &mockFolderRepoForImport{
+				folder: &model.Folder{
+					ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: "",
+				},
+			}
+			ds.MockedFolder = mockFolderRepo
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsFile := filepath.Join(tmpDir, "test.m3u")
+			Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
+
+			existingPls := &model.Playlist{
+				ID: "existing-id", Name: "Existing", Path: plsFile,
+				Sync: false, OwnerID: "123",
+			}
+			mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
+
+			pls, err := ps.ImportFile(ctx, plsFile, true)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.ID).To(Equal("existing-id"))
+			Expect(pls.Sync).To(BeTrue())
+		})
+	})
+
 	Describe("ImportM3U", func() {
 		var repo *mockedMediaFileFromListRepo
 		BeforeEach(func() {
@@ -821,6 +970,7 @@ var _ = Describe("Playlists - Import", func() {
 		})
 
 		It("returns true if folder is in PlaylistsPath", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-playlists)")
 			conf.Server.PlaylistsPath = "other/**:playlists/**"
 			Expect(playlists.InPath(folder)).To(BeTrue())
 		})
@@ -921,3 +1071,15 @@ func (r *mockedMediaFileFromListRepo) FindByPaths(paths []string) (model.MediaFi
 	}
 	return mfs, nil
 }
+
+type mockFolderRepoForImport struct {
+	model.FolderRepository
+	folder *model.Folder
+}
+
+func (m *mockFolderRepoForImport) GetByPath(_ model.Library, _ string) (*model.Folder, error) {
+	if m.folder != nil {
+		return m.folder, nil
+	}
+	return nil, model.ErrNotFound
+}

core/playlists/parse_m3u.go

@@ -163,17 +163,26 @@ type libraryMatcher struct {
 // findLibraryForPath finds which library contains the given absolute path.
 // Returns library ID and path, or 0 and empty string if not found.
 func (lm *libraryMatcher) findLibraryForPath(absolutePath string) (int, string) {
+	lib, ok := lm.findLibrary(absolutePath)
+	if !ok {
+		return 0, ""
+	}
+	return lib.ID, filepath.Clean(lib.Path)
+}
+
+// findLibrary checks if the absolute path is under any of the library paths.
+func (lm *libraryMatcher) findLibrary(absolutePath string) (model.Library, bool) {
 	// Check sorted libraries (longest path first) to find the best match
 	for i, cleanLibPath := range lm.cleanedPaths {
 		// Check if absolutePath is under this library path
 		if strings.HasPrefix(absolutePath, cleanLibPath) {
 			// Ensure it's a proper path boundary (not just a prefix)
 			if len(absolutePath) == len(cleanLibPath) || absolutePath[len(cleanLibPath)] == filepath.Separator {
-				return lm.libraries[i].ID, cleanLibPath
+				return lm.libraries[i], true
 			}
 		}
 	}
-	return 0, ""
+	return model.Library{}, false
 }
 
 // newLibraryMatcher creates a libraryMatcher with libraries sorted by path length (longest first).

core/playlists/parse_m3u_test.go

@@ -15,6 +15,7 @@ var _ = Describe("libraryMatcher", func() {
 	ctx := context.Background()
 
 	BeforeEach(func() {
+		tests.SkipOnWindows("path separator bug (#TBD-path-sep-playlists)")
 		mockLibRepo = &tests.MockLibraryRepo{}
 		ds = &tests.MockDataStore{
 			MockedLibrary: mockLibRepo,
@@ -196,6 +197,7 @@ var _ = Describe("pathResolver", func() {
 	ctx := context.Background()
 
 	BeforeEach(func() {
+		tests.SkipOnWindows("path separator bug (#TBD-path-sep-playlists)")
 		mockLibRepo = &tests.MockLibraryRepo{}
 		ds = &tests.MockDataStore{
 			MockedLibrary: mockLibRepo,

core/playlists/playlists.go

@@ -42,10 +42,11 @@ type Playlists interface {
 	RemoveImage(ctx context.Context, playlistID string) error
 
 	// Import
-	ImportFile(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error)
+	ImportFile(ctx context.Context, absolutePath string, sync bool) (*model.Playlist, error)
+	ImportFromFolder(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error)
 	ImportM3U(ctx context.Context, reader io.Reader) (*model.Playlist, error)
 
-	// REST adapters (follows Share/Library pattern)
+	// REST adapters
 	NewRepository(ctx context.Context) rest.Repository
 	TracksRepository(ctx context.Context, playlistId string, refreshSmartPlaylist bool) rest.Repository
 }

core/playlists/rest_adapter.go

@@ -3,9 +3,11 @@ package playlists
 import (
 	"context"
 	"errors"
+	"reflect"
 
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/request"
 )
 
@@ -32,8 +34,8 @@ func (r *playlistRepositoryWrapper) Save(entity any) (string, error) {
 	return r.service.savePlaylist(r.ctx, entity.(*model.Playlist))
 }
 
-func (r *playlistRepositoryWrapper) Update(id string, entity any, cols ...string) error {
-	return r.service.updatePlaylistEntity(r.ctx, id, entity.(*model.Playlist), cols...)
+func (r *playlistRepositoryWrapper) Update(id string, entity any, _ ...string) error {
+	return r.service.updatePlaylistEntity(r.ctx, id, entity.(*model.Playlist))
 }
 
 func (r *playlistRepositoryWrapper) Delete(id string) error {
@@ -77,7 +79,7 @@ func (s *playlists) savePlaylist(ctx context.Context, pls *model.Playlist) (stri
 
 // updatePlaylistEntity updates playlist metadata with permission checks.
 // Used by the REST API wrapper.
-func (s *playlists) updatePlaylistEntity(ctx context.Context, id string, entity *model.Playlist, cols ...string) error {
+func (s *playlists) updatePlaylistEntity(ctx context.Context, id string, entity *model.Playlist) error {
 	current, err := s.checkWritable(ctx, id)
 	if err != nil {
 		switch {
@@ -93,11 +95,45 @@ func (s *playlists) updatePlaylistEntity(ctx context.Context, id string, entity
 	if !usr.IsAdmin && entity.OwnerID != "" && entity.OwnerID != current.OwnerID {
 		return rest.ErrPermissionDenied
 	}
-	// Apply ownership change (admin only)
-	if entity.OwnerID != "" {
-		current.OwnerID = entity.OwnerID
+
+	contentChanged := entity.Name != current.Name ||
+		entity.Comment != current.Comment ||
+		(entity.OwnerID != "" && entity.OwnerID != current.OwnerID) ||
+		!rulesEqual(current.Rules, entity.Rules)
+
+	if contentChanged {
+		if entity.OwnerID != "" {
+			current.OwnerID = entity.OwnerID
+		}
+		current.Rules = entity.Rules
+		if current.Path != "" && current.Sync != entity.Sync {
+			current.Sync = entity.Sync
+		}
+		return s.updateMetadata(ctx, s.ds, current, &entity.Name, &entity.Comment, &entity.Public)
 	}
-	// Apply smart playlist rules update
-	current.Rules = entity.Rules
-	return s.updateMetadata(ctx, s.ds, current, &entity.Name, &entity.Comment, &entity.Public)
+
+	// Only sync/public changed — skip updatedAt so cover art URLs stay stable
+	var cols []string
+	if current.Path != "" && current.Sync != entity.Sync {
+		current.Sync = entity.Sync
+		cols = append(cols, "sync")
+	}
+	if current.Public != entity.Public {
+		current.Public = entity.Public
+		cols = append(cols, "public")
+	}
+	if len(cols) == 0 {
+		return nil
+	}
+	return s.ds.Playlist(ctx).Put(current, cols...)
+}
+
+func rulesEqual(a, b *criteria.Criteria) bool {
+	if a == b {
+		return true
+	}
+	if a == nil || b == nil {
+		return false
+	}
+	return reflect.DeepEqual(a, b)
 }

core/playlists/rest_adapter_test.go

@@ -142,6 +142,76 @@ var _ = Describe("REST Adapter", func() {
 				Expect(mockPlsRepo.Last.Rules).To(Equal(newRules))
 			})
 
+			It("allows toggling sync for file-backed playlists", func() {
+				originalTime := time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC)
+				mockPlsRepo.Data["file-pls"] = &model.Playlist{
+					ID:        "file-pls",
+					Name:      "File Playlist",
+					OwnerID:   "user-1",
+					Path:      "/music/playlist.m3u",
+					Sync:      true,
+					UpdatedAt: originalTime,
+				}
+				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+				repo = ps.NewRepository(ctx).(rest.Persistable)
+				pls := &model.Playlist{Name: "File Playlist", Sync: false}
+				err := repo.Update("file-pls", pls)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockPlsRepo.Last.Sync).To(BeFalse())
+				Expect(mockPlsRepo.Last.UpdatedAt).To(Equal(originalTime))
+			})
+
+			It("does not allow setting sync on non-file-backed playlists", func() {
+				mockPlsRepo.Data["manual-pls"] = &model.Playlist{
+					ID:      "manual-pls",
+					Name:    "Manual Playlist",
+					OwnerID: "user-1",
+					Path:    "",
+					Sync:    false,
+				}
+				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+				repo = ps.NewRepository(ctx).(rest.Persistable)
+				pls := &model.Playlist{Name: "Manual Playlist", Sync: true}
+				err := repo.Update("manual-pls", pls)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockPlsRepo.Last).To(BeNil())
+			})
+
+			It("does not bump updatedAt when only public changes", func() {
+				originalTime := time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC)
+				mockPlsRepo.Data["pls-pub"] = &model.Playlist{
+					ID:        "pls-pub",
+					Name:      "My Playlist",
+					OwnerID:   "user-1",
+					Public:    false,
+					UpdatedAt: originalTime,
+				}
+				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+				repo = ps.NewRepository(ctx).(rest.Persistable)
+				pls := &model.Playlist{Name: "My Playlist", Public: true}
+				err := repo.Update("pls-pub", pls)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockPlsRepo.Last.Public).To(BeTrue())
+				Expect(mockPlsRepo.Last.UpdatedAt).To(Equal(originalTime))
+			})
+
+			It("bumps updatedAt when name changes along with sync", func() {
+				mockPlsRepo.Data["file-pls2"] = &model.Playlist{
+					ID:      "file-pls2",
+					Name:    "Old Name",
+					OwnerID: "user-1",
+					Path:    "/music/playlist.m3u",
+					Sync:    true,
+				}
+				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+				repo = ps.NewRepository(ctx).(rest.Persistable)
+				pls := &model.Playlist{Name: "New Name", Sync: false}
+				err := repo.Update("file-pls2", pls)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockPlsRepo.Last.Name).To(Equal("New Name"))
+				Expect(mockPlsRepo.Last.Sync).To(BeFalse())
+			})
+
 			It("returns rest.ErrNotFound when playlist doesn't exist", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
 				repo = ps.NewRepository(ctx).(rest.Persistable)

core/publicurl/publicurl.go

@@ -45,6 +45,9 @@ func PublicURL(req *http.Request, u string, params url.Values) string {
 	}
 	buildUrl.Scheme = shareUrl.Scheme
 	buildUrl.Host = shareUrl.Host
+	if basePath := strings.TrimRight(shareUrl.Path, "/"); basePath != "" {
+		buildUrl.Path = path.Join(basePath, buildUrl.Path)
+	}
 	if len(params) > 0 {
 		buildUrl.RawQuery = params.Encode()
 	}

core/publicurl/publicurl_test.go

@@ -56,6 +56,31 @@ var _ = Describe("Public URL Utilities", func() {
 			})
 		})
 
+		When("ShareURL includes a path", func() {
+			BeforeEach(func() {
+				conf.Server.ShareURL = "https://example.com/navi"
+			})
+
+			It("prepends the ShareURL path to the resource", func() {
+				r, _ := http.NewRequest("GET", "http://localhost/test", nil)
+				result := publicurl.PublicURL(r, "/share/img/hash", nil)
+				Expect(result).To(Equal("https://example.com/navi/share/img/hash"))
+			})
+
+			It("prepends the ShareURL path and includes query parameters", func() {
+				r, _ := http.NewRequest("GET", "http://localhost/test", nil)
+				params := url.Values{"size": []string{"600"}}
+				result := publicurl.PublicURL(r, "/share/img/hash", params)
+				Expect(result).To(Equal("https://example.com/navi/share/img/hash?size=600"))
+			})
+
+			It("handles trailing slash in ShareURL path", func() {
+				conf.Server.ShareURL = "https://example.com/navi/"
+				result := publicurl.PublicURL(nil, "/share/img/hash", nil)
+				Expect(result).To(Equal("https://example.com/navi/share/img/hash"))
+			})
+		})
+
 		When("ShareURL is not set", func() {
 			BeforeEach(func() {
 				conf.Server.ShareURL = ""

core/scrobbler/buffered_scrobbler.go

@@ -80,6 +80,14 @@ func (b *bufferedScrobbler) Scrobble(ctx context.Context, userId string, s Scrob
 	return nil
 }
 
+func (b *bufferedScrobbler) PlaybackReport(ctx context.Context, info PlaybackSession) error {
+	s, ok := b.loader()
+	if !ok {
+		return errors.New("scrobbler not available")
+	}
+	return s.PlaybackReport(ctx, info)
+}
+
 func (b *bufferedScrobbler) sendWakeSignal() {
 	// Don't block if the previous signal was not read yet
 	select {

core/scrobbler/interfaces.go

@@ -23,6 +23,7 @@ type Scrobbler interface {
 	IsAuthorized(ctx context.Context, userId string) bool
 	NowPlaying(ctx context.Context, userId string, track *model.MediaFile, position int) error
 	Scrobble(ctx context.Context, userId string, s Scrobble) error
+	PlaybackReport(ctx context.Context, info PlaybackSession) error
 }
 
 type Constructor func(ds model.DataStore) Scrobbler

core/scrobbler/nowplaying_worker.go

@@ -0,0 +1,78 @@
+package scrobbler
+
+import (
+	"context"
+	"time"
+
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+func (p *playTracker) enqueueNowPlaying(ctx context.Context, playerId string, userId string, track *model.MediaFile, position int) {
+	p.npMu.Lock()
+	defer p.npMu.Unlock()
+	ctx = context.WithoutCancel(ctx) // Prevent cancellation from affecting background processing
+	p.npQueue[playerId] = nowPlayingEntry{
+		ctx:      ctx,
+		userId:   userId,
+		track:    track,
+		position: position,
+	}
+	p.sendNowPlayingSignal()
+}
+
+func (p *playTracker) sendNowPlayingSignal() {
+	// Don't block if the previous signal was not read yet
+	select {
+	case p.npSignal <- struct{}{}:
+	default:
+	}
+}
+
+func (p *playTracker) nowPlayingWorker() {
+	defer close(p.workerDone)
+	for {
+		select {
+		case <-p.shutdown:
+			return
+		case <-time.After(time.Second):
+		case <-p.npSignal:
+		}
+
+		p.npMu.Lock()
+		if len(p.npQueue) == 0 {
+			p.npMu.Unlock()
+			continue
+		}
+
+		// Keep a copy of the entries to process and clear the queue
+		entries := p.npQueue
+		p.npQueue = make(map[string]nowPlayingEntry)
+		p.npMu.Unlock()
+
+		// Process entries without holding lock
+		for _, entry := range entries {
+			p.dispatchNowPlaying(entry.ctx, entry.userId, entry.track, entry.position)
+		}
+	}
+}
+
+func (p *playTracker) dispatchNowPlaying(ctx context.Context, userId string, t *model.MediaFile, position int) {
+	if t.Artist == consts.UnknownArtist {
+		log.Debug(ctx, "Ignoring external NowPlaying update for track with unknown artist", "track", t.Title, "artist", t.Artist)
+		return
+	}
+	allScrobblers := p.getActiveScrobblers()
+	for name, s := range allScrobblers {
+		if !s.IsAuthorized(ctx, userId) {
+			continue
+		}
+		log.Debug(ctx, "Sending NowPlaying update", "scrobbler", name, "track", t.Title, "artist", t.Artist, "position", position)
+		err := s.NowPlaying(ctx, userId, t, position)
+		if err != nil {
+			log.Error(ctx, "Error sending PlaybackSession", "scrobbler", name, "track", t.Title, "artist", t.Artist, err)
+			continue
+		}
+	}
+}

core/scrobbler/play_tracker.go

@@ -3,7 +3,7 @@ package scrobbler
 import (
 	"context"
 	"maps"
-	"sort"
+	"slices"
 	"sync"
 	"time"
 
@@ -17,13 +17,32 @@ import (
 	"github.com/navidrome/navidrome/utils/singleton"
 )
 
-type NowPlayingInfo struct {
-	MediaFile  model.MediaFile
-	Start      time.Time
-	Position   int
-	Username   string
-	PlayerId   string
-	PlayerName string
+const (
+	StateStarting = "starting"
+	StatePlaying  = "playing"
+	StatePaused   = "paused"
+	StateStopped  = "stopped"
+	StateExpired  = "expired"
+)
+
+var ValidStates = map[string]bool{
+	StateStarting: true,
+	StatePlaying:  true,
+	StatePaused:   true,
+	StateStopped:  true,
+}
+
+type PlaybackSession struct {
+	MediaFile    model.MediaFile
+	Start        time.Time
+	UserId       string
+	Username     string
+	PlayerId     string
+	PlayerName   string
+	State        string
+	PositionMs   int64
+	PlaybackRate float64
+	LastReport   time.Time
 }
 
 type Submission struct {
@@ -31,6 +50,16 @@ type Submission struct {
 	Timestamp time.Time
 }
 
+type ReportPlaybackParams struct {
+	MediaId        string
+	PositionMs     int64
+	State          string
+	PlaybackRate   float64
+	IgnoreScrobble bool
+	ClientId       string
+	ClientName     string
+}
+
 type nowPlayingEntry struct {
 	ctx      context.Context
 	userId   string
@@ -38,10 +67,15 @@ type nowPlayingEntry struct {
 	position int
 }
 
+type playbackReportEntry struct {
+	ctx  context.Context
+	info PlaybackSession
+}
+
 type PlayTracker interface {
-	NowPlaying(ctx context.Context, playerId string, playerName string, trackId string, position int) error
-	GetNowPlaying(ctx context.Context) ([]NowPlayingInfo, error)
+	GetNowPlaying(ctx context.Context) ([]PlaybackSession, error)
 	Submit(ctx context.Context, submissions []Submission) error
+	ReportPlayback(ctx context.Context, params ReportPlaybackParams) error
 }
 
 // PluginLoader is a minimal interface for plugin manager usage in PlayTracker
@@ -54,7 +88,7 @@ type PluginLoader interface {
 type playTracker struct {
 	ds                model.DataStore
 	broker            events.Broker
-	playMap           cache.SimpleCache[string, NowPlayingInfo]
+	playMap           cache.SimpleCache[string, PlaybackSession]
 	builtinScrobblers map[string]Scrobbler
 	pluginScrobblers  map[string]Scrobbler
 	pluginLoader      PluginLoader
@@ -64,6 +98,10 @@ type playTracker struct {
 	npSignal          chan struct{}
 	shutdown          chan struct{}
 	workerDone        chan struct{}
+	prQueue           []playbackReportEntry
+	prMu              sync.Mutex
+	prSignal          chan struct{}
+	prWorkerDone      chan struct{}
 }
 
 func GetPlayTracker(ds model.DataStore, broker events.Broker, pluginManager PluginLoader) PlayTracker {
@@ -72,10 +110,14 @@ func GetPlayTracker(ds model.DataStore, broker events.Broker, pluginManager Plug
 	})
 }
 
-// This constructor only exists for testing. For normal usage, the PlayTracker has to be a singleton, returned by
-// the GetPlayTracker function above
+// NewPlayTracker creates a new PlayTracker instance. For normal usage, the PlayTracker has to be a singleton,
+// returned by the GetPlayTracker function above. This constructor is exported for testing.
+func NewPlayTracker(ds model.DataStore, broker events.Broker, pluginManager PluginLoader) PlayTracker {
+	return newPlayTracker(ds, broker, pluginManager)
+}
+
 func newPlayTracker(ds model.DataStore, broker events.Broker, pluginManager PluginLoader) *playTracker {
-	m := cache.NewSimpleCache[string, NowPlayingInfo]()
+	m := cache.NewSimpleCache[string, PlaybackSession]()
 	p := &playTracker{
 		ds:                ds,
 		playMap:           m,
@@ -87,12 +129,24 @@ func newPlayTracker(ds model.DataStore, broker events.Broker, pluginManager Plug
 		npSignal:          make(chan struct{}, 1),
 		shutdown:          make(chan struct{}),
 		workerDone:        make(chan struct{}),
+		prSignal:          make(chan struct{}, 1),
+		prWorkerDone:      make(chan struct{}),
 	}
-	if conf.Server.EnableNowPlaying {
-		m.OnExpiration(func(_ string, _ NowPlayingInfo) {
+	enableNowPlaying := conf.Server.EnableNowPlaying
+	m.OnExpiration(func(_ string, info PlaybackSession) {
+		log.Debug("PlaybackSession expired", "clientId", info.PlayerId, "mediaId", info.MediaFile.ID, "state",
+			info.State, "username", info.Username, "userId", info.UserId)
+		if enableNowPlaying {
 			broker.SendBroadcastMessage(context.Background(), &events.NowPlayingCount{Count: m.Len()})
-		})
-	}
+		}
+		ctx := request.WithUser(context.Background(), model.User{ID: info.UserId, UserName: info.Username})
+		if info.State != StateStopped {
+			log.Trace("Enqueueing PlaybackReport for expired session", "session", info)
+			info.State = StateExpired
+			info.LastReport = time.Now()
+			p.enqueuePlaybackReport(ctx, info)
+		}
+	})
 
 	var enabled []string
 	for name, constructor := range constructors {
@@ -107,13 +161,15 @@ func newPlayTracker(ds model.DataStore, broker events.Broker, pluginManager Plug
 	}
 	log.Debug("List of builtin scrobblers enabled", "names", enabled)
 	go p.nowPlayingWorker()
+	go p.playbackReportWorker()
 	return p
 }
 
-// stopNowPlayingWorker stops the background worker. This is primarily for testing.
-func (p *playTracker) stopNowPlayingWorker() {
+// stopBackgroundWorkers stops the background workers. This is primarily for testing.
+func (p *playTracker) stopBackgroundWorkers() {
 	close(p.shutdown)
-	<-p.workerDone // Wait for worker to finish
+	<-p.workerDone   // Wait for nowPlaying worker to finish
+	<-p.prWorkerDone // Wait for playbackReport worker to finish
 }
 
 // pluginNamesMatchScrobblers returns true if the set of pluginNames matches the keys in pluginScrobblers.
@@ -193,112 +249,151 @@ func (p *playTracker) getActiveScrobblers() map[string]Scrobbler {
 	return combined
 }
 
-func (p *playTracker) NowPlaying(ctx context.Context, playerId string, playerName string, trackId string, position int) error {
-	mf, err := p.ds.MediaFile(ctx).GetWithParticipants(trackId)
-	if err != nil {
-		log.Error(ctx, "Error retrieving mediaFile", "id", trackId, err)
-		return err
+func remainingTTL(durationSec float32, positionMs int64, rate float64) time.Duration {
+	if rate <= 0 {
+		rate = 1.0
 	}
+	remainingMs := float64(int64(durationSec*1000)-positionMs) / rate
+	remainingSec := max(int(remainingMs/1000), 0)
+	return time.Duration(remainingSec+5) * time.Second
+}
 
+func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackParams) error {
+	player, _ := request.PlayerFrom(ctx)
 	user, _ := request.UserFrom(ctx)
-	info := NowPlayingInfo{
-		MediaFile:  *mf,
-		Start:      time.Now(),
-		Position:   position,
-		Username:   user.UserName,
-		PlayerId:   playerId,
-		PlayerName: playerName,
+	clientId := params.ClientId
+	client := params.ClientName
+
+	now := time.Now()
+
+	switch params.State {
+	case StateStarting:
+		mf, err := p.ds.MediaFile(ctx).GetWithParticipants(params.MediaId)
+		if err != nil {
+			return err
+		}
+		info := PlaybackSession{
+			MediaFile:    *mf,
+			Start:        now,
+			UserId:       user.ID,
+			Username:     user.UserName,
+			PlayerId:     clientId,
+			PlayerName:   client,
+			State:        params.State,
+			PositionMs:   params.PositionMs,
+			PlaybackRate: params.PlaybackRate,
+			LastReport:   now,
+		}
+		err = p.playMap.AddWithTTL(clientId, info, remainingTTL(mf.Duration, params.PositionMs, params.PlaybackRate))
+		if err != nil {
+			log.Warn(ctx, "Error adding PlaybackSession to cache", "clientId", clientId, "mediaId", params.MediaId, "state", params.State, err)
+		}
+		p.enqueuePlaybackReport(ctx, info)
+
+	case StatePlaying, StatePaused:
+		info, getErr := p.playMap.Get(clientId)
+		if getErr != nil || info.MediaFile.ID != params.MediaId {
+			mf, err := p.ds.MediaFile(ctx).GetWithParticipants(params.MediaId)
+			if err != nil {
+				return err
+			}
+			info = PlaybackSession{
+				MediaFile:  *mf,
+				Start:      now.Add(-time.Duration(params.PositionMs) * time.Millisecond),
+				UserId:     user.ID,
+				Username:   user.UserName,
+				PlayerId:   clientId,
+				PlayerName: client,
+			}
+		}
+		info.State = params.State
+		info.PositionMs = params.PositionMs
+		info.PlaybackRate = params.PlaybackRate
+		info.LastReport = now
+		ttl := 30 * time.Minute
+		if params.State == StatePlaying {
+			ttl = remainingTTL(info.MediaFile.Duration, params.PositionMs, params.PlaybackRate)
+		}
+		log.Trace(ctx, "Updating PlaybackSession in cache", "clientId", clientId, "mediaId", params.MediaId, "state", params.State, "positionMs", params.PositionMs, "playbackRate", params.PlaybackRate, "ttl", ttl)
+		err := p.playMap.AddWithTTL(clientId, info, ttl)
+		if err != nil {
+			log.Warn(ctx, "Error updating PlaybackSession in cache", "clientId", clientId, "mediaId", params.MediaId, "state", params.State, err)
+		}
+		p.enqueuePlaybackReport(ctx, info)
+
+	case StateStopped:
+		var loadedMF *model.MediaFile
+		if !params.IgnoreScrobble && player.ScrobbleEnabled {
+			mf, err := p.ds.MediaFile(ctx).GetWithParticipants(params.MediaId)
+			if err != nil {
+				return err
+			}
+			loadedMF = mf
+			trackDurationMs := int64(mf.Duration * 1000)
+			threshold := min(trackDurationMs*50/100, 240_000)
+			if params.PositionMs >= threshold {
+				err = p.incPlay(ctx, mf, now)
+				if err != nil {
+					log.Warn(ctx, "Error updating play counts", "id", mf.ID, "track", mf.Title, "user", user.UserName, err)
+				}
+				p.dispatchScrobble(ctx, mf, now)
+			}
+		}
+		stoppedInfo := PlaybackSession{
+			UserId:       user.ID,
+			Username:     user.UserName,
+			PlayerId:     clientId,
+			PlayerName:   client,
+			State:        params.State,
+			PositionMs:   params.PositionMs,
+			PlaybackRate: params.PlaybackRate,
+			LastReport:   now,
+		}
+		if info, getErr := p.playMap.Get(clientId); getErr == nil {
+			stoppedInfo.MediaFile = info.MediaFile
+			stoppedInfo.Start = info.Start
+		} else {
+			mf := loadedMF
+			if mf == nil {
+				var mfErr error
+				mf, mfErr = p.ds.MediaFile(ctx).GetWithParticipants(params.MediaId)
+				if mfErr != nil {
+					return mfErr
+				}
+			}
+			stoppedInfo.MediaFile = *mf
+		}
+		p.enqueuePlaybackReport(ctx, stoppedInfo)
+		p.playMap.Remove(clientId)
 	}
 
-	// Calculate TTL based on remaining track duration. If position exceeds track duration,
-	// remaining is set to 0 to avoid negative TTL.
-	remaining := max(int(mf.Duration)-position, 0)
-	// Add 5 seconds buffer to ensure the NowPlaying info is available slightly longer than the track duration.
-	ttl := time.Duration(remaining+5) * time.Second
-	_ = p.playMap.AddWithTTL(playerId, info, ttl)
 	if conf.Server.EnableNowPlaying {
 		p.broker.SendBroadcastMessage(ctx, &events.NowPlayingCount{Count: p.playMap.Len()})
 	}
-	player, _ := request.PlayerFrom(ctx)
-	if player.ScrobbleEnabled {
-		p.enqueueNowPlaying(ctx, playerId, user.ID, mf, position)
+
+	if !params.IgnoreScrobble && player.ScrobbleEnabled &&
+		(params.State == StateStarting || params.State == StatePlaying) {
+		if info, err := p.playMap.Get(clientId); err == nil {
+			p.enqueueNowPlaying(ctx, clientId, user.ID, &info.MediaFile, int(params.PositionMs/1000))
+		}
 	}
+
 	return nil
 }
 
-func (p *playTracker) enqueueNowPlaying(ctx context.Context, playerId string, userId string, track *model.MediaFile, position int) {
-	p.npMu.Lock()
-	defer p.npMu.Unlock()
-	ctx = context.WithoutCancel(ctx) // Prevent cancellation from affecting background processing
-	p.npQueue[playerId] = nowPlayingEntry{
-		ctx:      ctx,
-		userId:   userId,
-		track:    track,
-		position: position,
-	}
-	p.sendNowPlayingSignal()
-}
-
-func (p *playTracker) sendNowPlayingSignal() {
-	// Don't block if the previous signal was not read yet
-	select {
-	case p.npSignal <- struct{}{}:
-	default:
-	}
-}
-
-func (p *playTracker) nowPlayingWorker() {
-	defer close(p.workerDone)
-	for {
-		select {
-		case <-p.shutdown:
-			return
-		case <-time.After(time.Second):
-		case <-p.npSignal:
-		}
-
-		p.npMu.Lock()
-		if len(p.npQueue) == 0 {
-			p.npMu.Unlock()
-			continue
-		}
-
-		// Keep a copy of the entries to process and clear the queue
-		entries := p.npQueue
-		p.npQueue = make(map[string]nowPlayingEntry)
-		p.npMu.Unlock()
-
-		// Process entries without holding lock
-		for _, entry := range entries {
-			p.dispatchNowPlaying(entry.ctx, entry.userId, entry.track, entry.position)
-		}
-	}
-}
-
-func (p *playTracker) dispatchNowPlaying(ctx context.Context, userId string, t *model.MediaFile, position int) {
-	if t.Artist == consts.UnknownArtist {
-		log.Debug(ctx, "Ignoring external NowPlaying update for track with unknown artist", "track", t.Title, "artist", t.Artist)
-		return
-	}
-	allScrobblers := p.getActiveScrobblers()
-	for name, s := range allScrobblers {
-		if !s.IsAuthorized(ctx, userId) {
-			continue
-		}
-		log.Debug(ctx, "Sending NowPlaying update", "scrobbler", name, "track", t.Title, "artist", t.Artist, "position", position)
-		err := s.NowPlaying(ctx, userId, t, position)
-		if err != nil {
-			log.Error(ctx, "Error sending NowPlayingInfo", "scrobbler", name, "track", t.Title, "artist", t.Artist, err)
-			continue
-		}
-	}
-}
-
-func (p *playTracker) GetNowPlaying(_ context.Context) ([]NowPlayingInfo, error) {
+func (p *playTracker) GetNowPlaying(_ context.Context) ([]PlaybackSession, error) {
 	res := p.playMap.Values()
-	sort.Slice(res, func(i, j int) bool {
-		return res[i].Start.After(res[j].Start)
+	slices.SortFunc(res, func(a, b PlaybackSession) int {
+		return b.Start.Compare(a.Start)
 	})
+	for i := range res {
+		if res[i].State == StatePlaying {
+			elapsed := time.Since(res[i].LastReport).Milliseconds()
+			estimated := res[i].PositionMs + int64(float64(elapsed)*res[i].PlaybackRate)
+			trackDurationMs := int64(res[i].MediaFile.Duration * 1000)
+			res[i].PositionMs = min(estimated, trackDurationMs)
+		}
+	}
 	return res, nil
 }
 

core/scrobbler/play_tracker_test.go

@@ -20,9 +20,6 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-// mockPluginLoader is a test implementation of PluginLoader for plugin scrobbler tests
-// Moved to top-level scope to avoid linter issues
-
 type mockPluginLoader struct {
 	mu         sync.RWMutex
 	names      []string
@@ -51,7 +48,7 @@ func (m *mockPluginLoader) LoadScrobbler(name string) (Scrobbler, bool) {
 var _ = Describe("PlayTracker", func() {
 	var ctx context.Context
 	var ds model.DataStore
-	var tracker PlayTracker
+	var tracker *playTracker
 	var eventBroker *fakeEventBroker
 	var track model.MediaFile
 	var album model.Album
@@ -74,7 +71,7 @@ var _ = Describe("PlayTracker", func() {
 		})
 		eventBroker = &fakeEventBroker{}
 		tracker = newPlayTracker(ds, eventBroker, nil)
-		tracker.(*playTracker).builtinScrobblers["fake"] = fake // Bypass buffering for tests
+		tracker.builtinScrobblers["fake"] = fake // Bypass buffering for tests
 
 		track = model.MediaFile{
 			ID:             "123",
@@ -99,88 +96,12 @@ var _ = Describe("PlayTracker", func() {
 
 	AfterEach(func() {
 		// Stop the worker goroutine to prevent data races between tests
-		tracker.(*playTracker).stopNowPlayingWorker()
+		tracker.stopBackgroundWorkers()
 	})
 
 	It("does not register disabled scrobblers", func() {
-		Expect(tracker.(*playTracker).builtinScrobblers).To(HaveKey("fake"))
-		Expect(tracker.(*playTracker).builtinScrobblers).ToNot(HaveKey("disabled"))
-	})
-
-	Describe("NowPlaying", func() {
-		It("sends track to agent", func() {
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
-			Expect(err).ToNot(HaveOccurred())
-			Eventually(func() bool { return fake.GetNowPlayingCalled() }).Should(BeTrue())
-			Expect(fake.GetUserID()).To(Equal("u-1"))
-			Expect(fake.GetTrack().ID).To(Equal("123"))
-			Expect(fake.GetTrack().Participants).To(Equal(track.Participants))
-		})
-		It("does not send track to agent if user has not authorized", func() {
-			fake.Authorized = false
-
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
-
-			Expect(err).ToNot(HaveOccurred())
-			Expect(fake.GetNowPlayingCalled()).To(BeFalse())
-		})
-		It("does not send track to agent if player is not enabled to send scrobbles", func() {
-			ctx = request.WithPlayer(ctx, model.Player{ScrobbleEnabled: false})
-
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
-
-			Expect(err).ToNot(HaveOccurred())
-			Expect(fake.GetNowPlayingCalled()).To(BeFalse())
-		})
-		It("does not send track to agent if artist is unknown", func() {
-			track.Artist = consts.UnknownArtist
-
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
-
-			Expect(err).ToNot(HaveOccurred())
-			Expect(fake.GetNowPlayingCalled()).To(BeFalse())
-		})
-
-		It("stores position when greater than zero", func() {
-			pos := 42
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", pos)
-			Expect(err).ToNot(HaveOccurred())
-
-			Eventually(func() int { return fake.GetPosition() }).Should(Equal(pos))
-
-			playing, err := tracker.GetNowPlaying(ctx)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(playing).To(HaveLen(1))
-			Expect(playing[0].Position).To(Equal(pos))
-		})
-
-		It("sends event with count", func() {
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
-			Expect(err).ToNot(HaveOccurred())
-			eventList := eventBroker.getEvents()
-			Expect(eventList).ToNot(BeEmpty())
-			evt, ok := eventList[0].(*events.NowPlayingCount)
-			Expect(ok).To(BeTrue())
-			Expect(evt.Count).To(Equal(1))
-		})
-
-		It("does not send event when disabled", func() {
-			conf.Server.EnableNowPlaying = false
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(eventBroker.getEvents()).To(BeEmpty())
-		})
-
-		It("passes user to scrobbler via context (fix for issue #4787)", func() {
-			ctx = request.WithUser(ctx, model.User{ID: "u-1", UserName: "testuser"})
-			ctx = request.WithPlayer(ctx, model.Player{ScrobbleEnabled: true})
-
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
-			Expect(err).ToNot(HaveOccurred())
-			Eventually(func() bool { return fake.GetNowPlayingCalled() }).Should(BeTrue())
-			// Verify the username was passed through async dispatch via context
-			Eventually(func() string { return fake.GetUsername() }).Should(Equal("testuser"))
-		})
+		Expect(tracker.builtinScrobblers).To(HaveKey("fake"))
+		Expect(tracker.builtinScrobblers).ToNot(HaveKey("disabled"))
 	})
 
 	Describe("GetNowPlaying", func() {
@@ -188,10 +109,16 @@ var _ = Describe("PlayTracker", func() {
 			track2 := track
 			track2.ID = "456"
 			_ = ds.MediaFile(ctx).Put(&track2)
-			ctx = request.WithUser(GinkgoT().Context(), model.User{UserName: "user-1"})
-			_ = tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
-			ctx = request.WithUser(GinkgoT().Context(), model.User{UserName: "user-2"})
-			_ = tracker.NowPlaying(ctx, "player-2", "player-two", "456", 0)
+			ctx1 := request.WithUser(GinkgoT().Context(), model.User{UserName: "user-1"})
+			ctx1 = request.WithPlayer(ctx1, model.Player{ScrobbleEnabled: true})
+			_ = tracker.ReportPlayback(ctx1, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: StatePlaying, PlaybackRate: 1.0, ClientId: "player-1", ClientName: "player-one",
+			})
+			ctx2 := request.WithUser(GinkgoT().Context(), model.User{UserName: "user-2"})
+			ctx2 = request.WithPlayer(ctx2, model.Player{ScrobbleEnabled: true})
+			_ = tracker.ReportPlayback(ctx2, ReportPlaybackParams{
+				MediaId: "456", PositionMs: 0, State: StatePlaying, PlaybackRate: 1.0, ClientId: "player-2", ClientName: "player-two",
+			})
 
 			playing, err := tracker.GetNowPlaying(ctx)
 
@@ -211,8 +138,8 @@ var _ = Describe("PlayTracker", func() {
 
 	Describe("Expiration events", func() {
 		It("sends event when entry expires", func() {
-			info := NowPlayingInfo{MediaFile: track, Start: time.Now(), Username: "user"}
-			_ = tracker.(*playTracker).playMap.AddWithTTL("player-1", info, 10*time.Millisecond)
+			info := PlaybackSession{MediaFile: track, Start: time.Now(), Username: "user"}
+			_ = tracker.playMap.AddWithTTL("player-1", info, 10*time.Millisecond)
 			Eventually(func() int { return len(eventBroker.getEvents()) }).Should(BeNumerically(">", 0))
 			eventList := eventBroker.getEvents()
 			evt, ok := eventList[len(eventList)-1].(*events.NowPlayingCount)
@@ -223,10 +150,48 @@ var _ = Describe("PlayTracker", func() {
 		It("does not send event when disabled", func() {
 			conf.Server.EnableNowPlaying = false
 			tracker = newPlayTracker(ds, eventBroker, nil)
-			info := NowPlayingInfo{MediaFile: track, Start: time.Now(), Username: "user"}
-			_ = tracker.(*playTracker).playMap.AddWithTTL("player-2", info, 10*time.Millisecond)
+			info := PlaybackSession{MediaFile: track, Start: time.Now(), Username: "user"}
+			_ = tracker.playMap.AddWithTTL("player-2", info, 10*time.Millisecond)
 			Consistently(func() int { return len(eventBroker.getEvents()) }).Should(Equal(0))
 		})
+
+		It("sends expired playback report when session expires", func() {
+			info := PlaybackSession{
+				MediaFile:  track,
+				Start:      time.Now(),
+				UserId:     "u-1",
+				Username:   "user",
+				PlayerId:   "player-3",
+				PlayerName: "test-player",
+				State:      StatePlaying,
+				PositionMs: 5000,
+			}
+			_ = tracker.playMap.AddWithTTL("player-3", info, 10*time.Millisecond)
+			Eventually(func() *PlaybackSession {
+				return fake.LastPlaybackReport.Load()
+			}).ShouldNot(BeNil())
+			report := fake.LastPlaybackReport.Load()
+			Expect(report.State).To(Equal(StateExpired))
+			Expect(report.MediaFile.ID).To(Equal("123"))
+			Expect(report.PlayerId).To(Equal("player-3"))
+		})
+
+		It("does not send expired report when session was already stopped", func() {
+			info := PlaybackSession{
+				MediaFile:  track,
+				Start:      time.Now(),
+				UserId:     "u-1",
+				Username:   "user",
+				PlayerId:   "player-4",
+				PlayerName: "test-player",
+				State:      StateStopped,
+				PositionMs: 180000,
+			}
+			_ = tracker.playMap.AddWithTTL("player-4", info, 10*time.Millisecond)
+			Consistently(func() *PlaybackSession {
+				return fake.LastPlaybackReport.Load()
+			}).Should(BeNil())
+		})
 	})
 
 	Describe("Submit", func() {
@@ -336,6 +301,532 @@ var _ = Describe("PlayTracker", func() {
 		})
 	})
 
+	Describe("ReportPlayback", func() {
+		const defaultClientId = "client-1"
+
+		BeforeEach(func() {
+			ctx = request.WithPlayer(ctx, model.Player{ID: "p1", ScrobbleEnabled: true})
+		})
+
+		It("creates entry on starting and removes on stopped", func() {
+			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+			})
+			Expect(err).ToNot(HaveOccurred())
+
+			playing, err := tracker.GetNowPlaying(ctx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(playing).To(HaveLen(1))
+			Expect(playing[0].State).To(Equal("starting"))
+			Expect(playing[0].MediaFile.ID).To(Equal("123"))
+
+			err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				IgnoreScrobble: true,
+			})
+			Expect(err).ToNot(HaveOccurred())
+
+			playing, err = tracker.GetNowPlaying(ctx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(playing).To(BeEmpty())
+		})
+
+		It("full lifecycle: starting -> playing -> paused -> playing -> stopped", func() {
+			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+			})
+			Expect(err).ToNot(HaveOccurred())
+			err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 10000, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
+			})
+			Expect(err).ToNot(HaveOccurred())
+			playing, err := tracker.GetNowPlaying(ctx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(playing).To(HaveLen(1))
+			Expect(playing[0].State).To(Equal("playing"))
+			Expect(playing[0].PositionMs).To(BeNumerically(">=", int64(10000)))
+
+			err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 30000, State: "paused", PlaybackRate: 1.0, ClientId: defaultClientId,
+			})
+			Expect(err).ToNot(HaveOccurred())
+			playing, err = tracker.GetNowPlaying(ctx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(playing[0].State).To(Equal("paused"))
+			Expect(playing[0].PositionMs).To(Equal(int64(30000)))
+
+			err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 30000, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
+			})
+			Expect(err).ToNot(HaveOccurred())
+
+			err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 100000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+			})
+			Expect(err).ToNot(HaveOccurred())
+			playing, err = tracker.GetNowPlaying(ctx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(playing).To(BeEmpty())
+		})
+
+		It("starting replaces existing entry for same player", func() {
+			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 50000, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
+			})
+			Expect(err).ToNot(HaveOccurred())
+			err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+			})
+			Expect(err).ToNot(HaveOccurred())
+			playing, err := tracker.GetNowPlaying(ctx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(playing).To(HaveLen(1))
+			Expect(playing[0].State).To(Equal("starting"))
+			Expect(playing[0].PositionMs).To(Equal(int64(0)))
+		})
+
+		It("multiple players have independent sessions", func() {
+			ctx1 := request.WithUser(ctx, model.User{ID: "u-1", UserName: "user1"})
+			ctx1 = request.WithPlayer(ctx1, model.Player{ID: "p1", ScrobbleEnabled: true})
+
+			ctx2 := request.WithUser(ctx, model.User{ID: "u-1", UserName: "user1"})
+			ctx2 = request.WithPlayer(ctx2, model.Player{ID: "p2", ScrobbleEnabled: true})
+
+			track2 := track
+			track2.ID = "456"
+			_ = ds.MediaFile(ctx).Put(&track2)
+
+			err := tracker.ReportPlayback(ctx1, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: "playing", PlaybackRate: 1.0, ClientId: "client-1",
+			})
+			Expect(err).ToNot(HaveOccurred())
+			err = tracker.ReportPlayback(ctx2, ReportPlaybackParams{
+				MediaId: "456", PositionMs: 0, State: "playing", PlaybackRate: 1.0, ClientId: "client-2",
+			})
+			Expect(err).ToNot(HaveOccurred())
+			playing, err := tracker.GetNowPlaying(ctx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(playing).To(HaveLen(2))
+		})
+
+		Describe("SSE broadcast on state change", func() {
+			BeforeEach(func() {
+				eventBroker = &fakeEventBroker{}
+				tracker = newPlayTracker(ds, eventBroker, nil)
+				tracker.builtinScrobblers["fake"] = fake
+			})
+
+			It("broadcasts NowPlayingCount on every state change", func() {
+				// starting -> count should be 1
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				evts := eventBroker.getEvents()
+				Expect(evts).To(HaveLen(1))
+				Expect(evts[0].(*events.NowPlayingCount).Count).To(Equal(1))
+
+				// playing -> count should be 1
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 10000, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				evts = eventBroker.getEvents()
+				Expect(evts).To(HaveLen(2))
+				Expect(evts[1].(*events.NowPlayingCount).Count).To(Equal(1))
+
+				// paused -> count should be 1
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 30000, State: "paused", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				evts = eventBroker.getEvents()
+				Expect(evts).To(HaveLen(3))
+				Expect(evts[2].(*events.NowPlayingCount).Count).To(Equal(1))
+
+				// stopped -> count should be 0
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 30000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+					IgnoreScrobble: true,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				evts = eventBroker.getEvents()
+				Expect(evts).To(HaveLen(4))
+				Expect(evts[3].(*events.NowPlayingCount).Count).To(Equal(0))
+			})
+
+			It("does NOT broadcast when EnableNowPlaying is false", func() {
+				conf.Server.EnableNowPlaying = false
+				tracker = newPlayTracker(ds, eventBroker, nil)
+				tracker.builtinScrobblers["fake"] = fake
+
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 10000, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(eventBroker.getEvents()).To(BeEmpty())
+			})
+		})
+
+		Describe("auto-scrobble", func() {
+			It("scrobbles on stopped when positionMs >= 50% of track", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 90000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(track.PlayCount).To(Equal(int64(1)))
+				Expect(album.PlayCount).To(Equal(int64(1)))
+				Expect(artist1.PlayCount).To(Equal(int64(1)))
+			})
+
+			It("scrobbles on stopped when positionMs >= 4 min for long tracks", func() {
+				longTrack := model.MediaFile{
+					ID: "long", Title: "Long Song", Album: "Album", AlbumID: "al-1",
+					Duration: 600,
+					Participants: map[model.Role]model.ParticipantList{
+						model.RoleArtist: []model.Participant{_p("ar-1", "Artist 1")},
+					},
+				}
+				_ = ds.MediaFile(ctx).Put(&longTrack)
+
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "long", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "long", PositionMs: 240000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(longTrack.PlayCount).To(Equal(int64(1)))
+			})
+
+			It("does NOT scrobble when positionMs below threshold", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 10000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(track.PlayCount).To(Equal(int64(0)))
+			})
+
+			It("does NOT scrobble when ignoreScrobble=true even if threshold met", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 90000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+					IgnoreScrobble: true,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(track.PlayCount).To(Equal(int64(0)))
+			})
+
+			It("does NOT scrobble when player ScrobbleEnabled=false even if threshold met", func() {
+				ctx = request.WithPlayer(ctx, model.Player{ID: "p1", ScrobbleEnabled: false})
+
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 90000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(track.PlayCount).To(Equal(int64(0)))
+			})
+
+			It("scrobbles twice for two separate sessions of same song", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 90000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 90000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(track.PlayCount).To(Equal(int64(2)))
+			})
+
+			It("dispatches to external scrobblers on auto-scrobble", func() {
+				fake.ScrobbleCalled.Store(false)
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 90000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(fake.ScrobbleCalled.Load()).To(BeTrue())
+			})
+		})
+
+		Describe("position estimation", func() {
+			It("estimates position for playing state based on elapsed time", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 10000, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				time.Sleep(50 * time.Millisecond)
+				playing, err := tracker.GetNowPlaying(ctx)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(playing).To(HaveLen(1))
+				Expect(playing[0].PositionMs).To(BeNumerically(">", int64(10000)))
+			})
+
+			It("does NOT estimate for paused", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 10000, State: "paused", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				time.Sleep(50 * time.Millisecond)
+				playing, err := tracker.GetNowPlaying(ctx)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(playing).To(HaveLen(1))
+				Expect(playing[0].PositionMs).To(Equal(int64(10000)))
+			})
+
+			It("does NOT estimate for starting", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				time.Sleep(50 * time.Millisecond)
+				playing, err := tracker.GetNowPlaying(ctx)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(playing).To(HaveLen(1))
+				Expect(playing[0].PositionMs).To(Equal(int64(0)))
+			})
+
+			It("respects playbackRate", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 10000, State: "playing", PlaybackRate: 2.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				time.Sleep(100 * time.Millisecond)
+				playing, err := tracker.GetNowPlaying(ctx)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(playing).To(HaveLen(1))
+				// At 2x speed, 100ms real time = ~200ms playback time
+				Expect(playing[0].PositionMs).To(BeNumerically(">", int64(10100)))
+			})
+
+			It("caps estimated position at track duration", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 179990, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				time.Sleep(50 * time.Millisecond)
+				playing, err := tracker.GetNowPlaying(ctx)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(playing).To(HaveLen(1))
+				Expect(playing[0].PositionMs).To(Equal(int64(180000))) // track.Duration * 1000
+			})
+
+		})
+
+		Describe("resilience (no prior starting)", func() {
+			It("playing without prior starting creates entry with Start approx now - positionMs", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 30000, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				playing, err := tracker.GetNowPlaying(ctx)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(playing).To(HaveLen(1))
+				Expect(playing[0].State).To(Equal("playing"))
+				expectedStart := time.Now().Add(-30 * time.Second)
+				Expect(playing[0].Start).To(BeTemporally("~", expectedStart, 2*time.Second))
+			})
+
+			It("paused without prior starting creates entry", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 30000, State: "paused", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				playing, err := tracker.GetNowPlaying(ctx)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(playing).To(HaveLen(1))
+				Expect(playing[0].State).To(Equal("paused"))
+			})
+
+			It("stopped without prior starting auto-scrobbles if threshold met", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 90000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(track.PlayCount).To(Equal(int64(1)))
+			})
+
+			It("stopped without prior starting does NOT scrobble if below threshold", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 10000, State: "stopped", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(track.PlayCount).To(Equal(int64(0)))
+			})
+		})
+
+		Describe("external scrobbler dispatch", func() {
+			It("dispatches NowPlaying on starting", func() {
+				fake.nowPlayingCalled.Store(false)
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Eventually(func() bool { return fake.GetNowPlayingCalled() }).Should(BeTrue())
+			})
+
+			It("dispatches NowPlaying on playing", func() {
+				fake.nowPlayingCalled.Store(false)
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 10000, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Eventually(func() bool { return fake.GetNowPlayingCalled() }).Should(BeTrue())
+			})
+
+			It("does NOT dispatch on paused", func() {
+				fake.nowPlayingCalled.Store(false)
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 10000, State: "paused", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Consistently(func() bool { return fake.GetNowPlayingCalled() }).Should(BeFalse())
+			})
+
+			It("does NOT dispatch when ignoreScrobble=true", func() {
+				fake.nowPlayingCalled.Store(false)
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+					IgnoreScrobble: true,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Consistently(func() bool { return fake.GetNowPlayingCalled() }).Should(BeFalse())
+			})
+
+			It("does NOT dispatch when ScrobbleEnabled=false", func() {
+				fake.nowPlayingCalled.Store(false)
+				ctx = request.WithPlayer(ctx, model.Player{ID: "p1", ScrobbleEnabled: false})
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Consistently(func() bool { return fake.GetNowPlayingCalled() }).Should(BeFalse())
+			})
+		})
+
+		Describe("PlaybackReport dispatch", func() {
+			It("dispatches PlaybackReport for starting state", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: StateStarting, PlaybackRate: 1.0,
+					ClientId: "client-1", ClientName: "Test Player",
+				})
+				Expect(err).ToNot(HaveOccurred())
+
+				Eventually(func() bool {
+					return fake.PlaybackReportCalled.Load()
+				}).Should(BeTrue())
+
+				info := fake.LastPlaybackReport.Load()
+				Expect(info).ToNot(BeNil())
+				Expect(info.MediaFile.ID).To(Equal("123"))
+				Expect(info.State).To(Equal(StateStarting))
+				Expect(info.PositionMs).To(Equal(int64(0)))
+				Expect(info.PlaybackRate).To(Equal(1.0))
+				Expect(info.PlayerId).To(Equal("client-1"))
+				Expect(info.PlayerName).To(Equal("Test Player"))
+			})
+
+			It("dispatches PlaybackReport for playing state", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: StateStarting, PlaybackRate: 1.0,
+					ClientId: "client-1", ClientName: "Test Player",
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Eventually(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeTrue())
+				fake.PlaybackReportCalled.Store(false)
+				fake.LastPlaybackReport.Store(nil)
+
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 30000, State: StatePlaying, PlaybackRate: 1.5,
+					ClientId: "client-1", ClientName: "Test Player",
+				})
+				Expect(err).ToNot(HaveOccurred())
+
+				Eventually(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeTrue())
+				info := fake.LastPlaybackReport.Load()
+				Expect(info.State).To(Equal(StatePlaying))
+				Expect(info.PositionMs).To(Equal(int64(30000)))
+				Expect(info.PlaybackRate).To(Equal(1.5))
+			})
+
+			It("dispatches PlaybackReport for paused state", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: StateStarting, PlaybackRate: 1.0,
+					ClientId: "client-1", ClientName: "Test Player",
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Eventually(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeTrue())
+				fake.PlaybackReportCalled.Store(false)
+				fake.LastPlaybackReport.Store(nil)
+
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 45000, State: StatePaused, PlaybackRate: 1.0,
+					ClientId: "client-1", ClientName: "Test Player",
+				})
+				Expect(err).ToNot(HaveOccurred())
+
+				Eventually(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeTrue())
+				info := fake.LastPlaybackReport.Load()
+				Expect(info.State).To(Equal(StatePaused))
+				Expect(info.PositionMs).To(Equal(int64(45000)))
+			})
+
+			It("dispatches PlaybackReport for stopped state", func() {
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 0, State: StateStarting, PlaybackRate: 1.0,
+					ClientId: "client-1", ClientName: "Test Player",
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Eventually(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeTrue())
+				fake.PlaybackReportCalled.Store(false)
+				fake.LastPlaybackReport.Store(nil)
+
+				err = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", PositionMs: 100000, State: StateStopped, PlaybackRate: 1.0,
+					ClientId: "client-1", ClientName: "Test Player",
+				})
+				Expect(err).ToNot(HaveOccurred())
+
+				Eventually(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeTrue())
+				info := fake.LastPlaybackReport.Load()
+				Expect(info.State).To(Equal(StateStopped))
+				Expect(info.PositionMs).To(Equal(int64(100000)))
+			})
+		})
+	})
+
 	Describe("Plugin scrobbler logic", func() {
 		var pluginLoader *mockPluginLoader
 		var pluginFake *fakeScrobbler
@@ -349,32 +840,37 @@ var _ = Describe("PlayTracker", func() {
 			tracker = newPlayTracker(ds, events.GetBroker(), pluginLoader)
 
 			// Bypass buffering for both built-in and plugin scrobblers
-			tracker.(*playTracker).builtinScrobblers["fake"] = fake
-			tracker.(*playTracker).pluginScrobblers["plugin1"] = pluginFake
+			tracker.builtinScrobblers["fake"] = fake
+			tracker.pluginScrobblers["plugin1"] = pluginFake
 		})
 
 		It("registers and uses plugin scrobbler for NowPlaying", func() {
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
+			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: StatePlaying, PlaybackRate: 1.0, ClientId: "player-1",
+			})
 			Expect(err).ToNot(HaveOccurred())
 			Eventually(func() bool { return pluginFake.GetNowPlayingCalled() }).Should(BeTrue())
 		})
 
 		It("removes plugin scrobbler if not present anymore", func() {
-			// First call: plugin present
-			_ = tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
+			_ = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: StatePlaying, PlaybackRate: 1.0, ClientId: "player-1",
+			})
 			Eventually(func() bool { return pluginFake.GetNowPlayingCalled() }).Should(BeTrue())
 			pluginFake.nowPlayingCalled.Store(false)
-			// Remove plugin
 			pluginLoader.SetNames([]string{})
-			_ = tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
-			// Should not be called since plugin was removed
+			_ = tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: StatePlaying, PlaybackRate: 1.0, ClientId: "player-1",
+			})
 			Consistently(func() bool { return pluginFake.GetNowPlayingCalled() }).Should(BeFalse())
 		})
 
 		It("calls both builtin and plugin scrobblers for NowPlaying", func() {
 			fake.nowPlayingCalled.Store(false)
 			pluginFake.nowPlayingCalled.Store(false)
-			err := tracker.NowPlaying(ctx, "player-1", "player-one", "123", 0)
+			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", PositionMs: 0, State: StatePlaying, PlaybackRate: 1.0, ClientId: "player-1",
+			})
 			Expect(err).ToNot(HaveOccurred())
 			Eventually(func() bool { return fake.GetNowPlayingCalled() }).Should(BeTrue())
 			Eventually(func() bool { return pluginFake.GetNowPlayingCalled() }).Should(BeTrue())
@@ -462,7 +958,7 @@ var _ = Describe("PlayTracker", func() {
 		})
 
 		AfterEach(func() {
-			pTracker.stopNowPlayingWorker()
+			pTracker.stopBackgroundWorkers()
 		})
 
 		It("uses the new plugin instance after reload (simulating config update)", func() {
@@ -550,16 +1046,36 @@ var _ = Describe("PlayTracker", func() {
 	})
 })
 
+var _ = DescribeTable("remainingTTL",
+	func(durationSec float32, positionMs int64, rate float64, expected time.Duration) {
+		Expect(remainingTTL(durationSec, positionMs, rate)).To(Equal(expected))
+	},
+	Entry("full track at 1x", float32(300), int64(0), 1.0, 305*time.Second),
+	Entry("halfway through at 1x", float32(300), int64(150000), 1.0, 155*time.Second),
+	Entry("near end at 1x", float32(300), int64(298000), 1.0, 7*time.Second),
+	Entry("at end of track", float32(300), int64(300000), 1.0, 5*time.Second),
+	Entry("past end of track", float32(300), int64(310000), 1.0, 5*time.Second),
+	Entry("2x speed halves remaining time", float32(300), int64(0), 2.0, 155*time.Second),
+	Entry("2x speed halfway", float32(300), int64(150000), 2.0, 80*time.Second),
+	Entry("0.5x speed doubles remaining time", float32(300), int64(0), 0.5, 605*time.Second),
+	Entry("zero rate defaults to 1x", float32(300), int64(0), 0.0, 305*time.Second),
+	Entry("negative rate defaults to 1x", float32(300), int64(0), -1.0, 305*time.Second),
+	Entry("short track", float32(3.5), int64(0), 1.0, 8*time.Second),
+	Entry("zero duration", float32(0), int64(0), 1.0, 5*time.Second),
+)
+
 type fakeScrobbler struct {
-	Authorized       bool
-	nowPlayingCalled atomic.Bool
-	ScrobbleCalled   atomic.Bool
-	userID           atomic.Pointer[string]
-	username         atomic.Pointer[string]
-	track            atomic.Pointer[model.MediaFile]
-	position         atomic.Int32
-	LastScrobble     atomic.Pointer[Scrobble]
-	Error            error
+	Authorized           bool
+	nowPlayingCalled     atomic.Bool
+	ScrobbleCalled       atomic.Bool
+	PlaybackReportCalled atomic.Bool
+	userID               atomic.Pointer[string]
+	username             atomic.Pointer[string]
+	track                atomic.Pointer[model.MediaFile]
+	position             atomic.Int32
+	LastScrobble         atomic.Pointer[Scrobble]
+	LastPlaybackReport   atomic.Pointer[PlaybackSession]
+	Error                error
 }
 
 func (f *fakeScrobbler) GetNowPlayingCalled() bool {
@@ -577,17 +1093,6 @@ func (f *fakeScrobbler) GetTrack() *model.MediaFile {
 	return f.track.Load()
 }
 
-func (f *fakeScrobbler) GetPosition() int {
-	return int(f.position.Load())
-}
-
-func (f *fakeScrobbler) GetUsername() string {
-	if p := f.username.Load(); p != nil {
-		return *p
-	}
-	return ""
-}
-
 func (f *fakeScrobbler) IsAuthorized(ctx context.Context, userId string) bool {
 	return f.Error == nil && f.Authorized
 }
@@ -623,6 +1128,17 @@ func (f *fakeScrobbler) Scrobble(ctx context.Context, userId string, s Scrobble)
 	return nil
 }
 
+func (f *fakeScrobbler) PlaybackReport(ctx context.Context, info PlaybackSession) error {
+	f.PlaybackReportCalled.Store(true)
+	if f.Error != nil {
+		return f.Error
+	}
+	uid := info.UserId
+	f.userID.Store(&uid)
+	f.LastPlaybackReport.Store(&info)
+	return nil
+}
+
 func _p(id, name string, sortName ...string) model.Participant {
 	p := model.Participant{Artist: model.Artist{ID: id, Name: name}}
 	if len(sortName) > 0 {
@@ -678,3 +1194,7 @@ func (m *mockBufferedScrobbler) NowPlaying(ctx context.Context, userId string, t
 func (m *mockBufferedScrobbler) Scrobble(ctx context.Context, userId string, s Scrobble) error {
 	return m.wrapped.Scrobble(ctx, userId, s)
 }
+
+func (m *mockBufferedScrobbler) PlaybackReport(ctx context.Context, info PlaybackSession) error {
+	return m.wrapped.PlaybackReport(ctx, info)
+}

core/scrobbler/playbackreport_worker.go

@@ -0,0 +1,64 @@
+package scrobbler
+
+import (
+	"context"
+
+	"github.com/navidrome/navidrome/log"
+)
+
+func (p *playTracker) enqueuePlaybackReport(ctx context.Context, info PlaybackSession) {
+	p.prMu.Lock()
+	defer p.prMu.Unlock()
+	ctx = context.WithoutCancel(ctx)
+	p.prQueue = append(p.prQueue, playbackReportEntry{
+		ctx:  ctx,
+		info: info,
+	})
+	p.sendPlaybackReportSignal()
+}
+
+func (p *playTracker) sendPlaybackReportSignal() {
+	select {
+	case p.prSignal <- struct{}{}:
+	default:
+	}
+}
+
+func (p *playTracker) playbackReportWorker() {
+	defer close(p.prWorkerDone)
+	for {
+		select {
+		case <-p.shutdown:
+			return
+		case <-p.prSignal:
+		}
+
+		p.prMu.Lock()
+		if len(p.prQueue) == 0 {
+			p.prMu.Unlock()
+			continue
+		}
+		entries := p.prQueue
+		p.prQueue = nil
+		p.prMu.Unlock()
+
+		allScrobblers := p.getActiveScrobblers()
+		for _, entry := range entries {
+			p.dispatchPlaybackReport(entry.ctx, entry.info, allScrobblers)
+		}
+	}
+}
+
+func (p *playTracker) dispatchPlaybackReport(ctx context.Context, info PlaybackSession, allScrobblers map[string]Scrobbler) {
+	for name, s := range allScrobblers {
+		if !s.IsAuthorized(ctx, info.UserId) {
+			continue
+		}
+		log.Debug(ctx, "Sending PlaybackReport", "scrobbler", name, "track", info.MediaFile.Title, "state", info.State, "positionMs", info.PositionMs)
+		err := s.PlaybackReport(ctx, info)
+		if err != nil {
+			log.Error(ctx, "Error sending PlaybackReport", "scrobbler", name, "track", info.MediaFile.Title, "state", info.State, err)
+			continue
+		}
+	}
+}

core/sonic/sonic.go

@@ -0,0 +1,130 @@
+package sonic
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/matcher"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+const capabilitySonicSimilarity = "SonicSimilarity"
+
+type SimilarResult struct {
+	Song       agents.Song
+	Similarity float64
+}
+
+type SimilarMatch struct {
+	MediaFile  model.MediaFile
+	Similarity float64
+}
+
+type Provider interface {
+	GetSonicSimilarTracks(ctx context.Context, mf *model.MediaFile, count int) ([]SimilarResult, error)
+	FindSonicPath(ctx context.Context, startMF, endMF *model.MediaFile, count int) ([]SimilarResult, error)
+}
+
+type PluginLoader interface {
+	PluginNames(capability string) []string
+	LoadSonicSimilarity(name string) (Provider, bool)
+}
+
+type Sonic struct {
+	ds           model.DataStore
+	pluginLoader PluginLoader
+	matcher      *matcher.Matcher
+}
+
+func New(ds model.DataStore, pluginLoader PluginLoader, matcher *matcher.Matcher) *Sonic {
+	return &Sonic{
+		ds:           ds,
+		pluginLoader: pluginLoader,
+		matcher:      matcher,
+	}
+}
+
+func (s *Sonic) HasProvider() bool {
+	return len(s.pluginLoader.PluginNames(capabilitySonicSimilarity)) > 0
+}
+
+func (s *Sonic) loadProvider() (Provider, error) {
+	names := s.pluginLoader.PluginNames(capabilitySonicSimilarity)
+	if len(names) == 0 {
+		return nil, model.ErrNotFound
+	}
+	provider, ok := s.pluginLoader.LoadSonicSimilarity(names[0])
+	if !ok {
+		return nil, model.ErrNotFound
+	}
+	return provider, nil
+}
+
+func (s *Sonic) resolveMatches(ctx context.Context, results []SimilarResult) ([]SimilarMatch, error) {
+	songs := make([]agents.Song, len(results))
+	for i, r := range results {
+		songs[i] = r.Song
+	}
+
+	matchMap, err := s.matcher.MatchSongsIndexed(ctx, songs)
+	if err != nil {
+		return nil, fmt.Errorf("matching songs to library: %w", err)
+	}
+
+	var matches []SimilarMatch
+	for i, r := range results {
+		if mf, ok := matchMap[i]; ok {
+			matches = append(matches, SimilarMatch{
+				MediaFile:  mf,
+				Similarity: r.Similarity,
+			})
+		}
+	}
+	return matches, nil
+}
+
+func (s *Sonic) GetSonicSimilarTracks(ctx context.Context, id string, count int) ([]SimilarMatch, error) {
+	provider, err := s.loadProvider()
+	if err != nil {
+		return nil, err
+	}
+
+	mf, err := s.ds.MediaFile(ctx).Get(id)
+	if err != nil {
+		return nil, fmt.Errorf("getting media file %s: %w", id, err)
+	}
+
+	results, err := provider.GetSonicSimilarTracks(ctx, mf, count)
+	if err != nil {
+		log.Error(ctx, "Plugin GetSonicSimilarTracks failed", "id", id, err)
+		return nil, err
+	}
+
+	return s.resolveMatches(ctx, results)
+}
+
+func (s *Sonic) FindSonicPath(ctx context.Context, startID, endID string, count int) ([]SimilarMatch, error) {
+	provider, err := s.loadProvider()
+	if err != nil {
+		return nil, err
+	}
+
+	startMF, err := s.ds.MediaFile(ctx).Get(startID)
+	if err != nil {
+		return nil, fmt.Errorf("getting start media file %s: %w", startID, err)
+	}
+	endMF, err := s.ds.MediaFile(ctx).Get(endID)
+	if err != nil {
+		return nil, fmt.Errorf("getting end media file %s: %w", endID, err)
+	}
+
+	results, err := provider.FindSonicPath(ctx, startMF, endMF, count)
+	if err != nil {
+		log.Error(ctx, "Plugin FindSonicPath failed", "startId", startID, "endId", endID, err)
+		return nil, err
+	}
+
+	return s.resolveMatches(ctx, results)
+}

core/sonic/sonic_suite_test.go

@@ -1,4 +1,4 @@
-package taglib
+package sonic_test
 
 import (
 	"testing"
@@ -9,9 +9,9 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-func TestTagLib(t *testing.T) {
-	tests.Init(t, true)
+func TestSonic(t *testing.T) {
+	tests.Init(t, false)
 	log.SetLevel(log.LevelFatal)
 	RegisterFailHandler(Fail)
-	RunSpecs(t, "TagLib Suite")
+	RunSpecs(t, "Sonic Suite")
 }

core/sonic/sonic_test.go

@@ -0,0 +1,146 @@
+package sonic_test
+
+import (
+	"context"
+	"errors"
+
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/matcher"
+	"github.com/navidrome/navidrome/core/sonic"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type mockPluginLoader struct {
+	names    []string
+	provider sonic.Provider
+	loadOk   bool
+}
+
+func (m *mockPluginLoader) PluginNames(capability string) []string {
+	if capability == "SonicSimilarity" {
+		return m.names
+	}
+	return nil
+}
+
+func (m *mockPluginLoader) LoadSonicSimilarity(name string) (sonic.Provider, bool) {
+	return m.provider, m.loadOk
+}
+
+type mockProvider struct {
+	similarResults []sonic.SimilarResult
+	similarErr     error
+	pathResults    []sonic.SimilarResult
+	pathErr        error
+}
+
+func (m *mockProvider) GetSonicSimilarTracks(_ context.Context, _ *model.MediaFile, _ int) ([]sonic.SimilarResult, error) {
+	return m.similarResults, m.similarErr
+}
+
+func (m *mockProvider) FindSonicPath(_ context.Context, _, _ *model.MediaFile, _ int) ([]sonic.SimilarResult, error) {
+	return m.pathResults, m.pathErr
+}
+
+var _ = Describe("Sonic", func() {
+	var (
+		ctx     context.Context
+		ds      *tests.MockDataStore
+		loader  *mockPluginLoader
+		service *sonic.Sonic
+	)
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+		ds = &tests.MockDataStore{}
+		loader = &mockPluginLoader{}
+	})
+
+	Describe("HasProvider", func() {
+		It("returns false when no plugins available", func() {
+			loader.names = nil
+			service = sonic.New(ds, loader, nil)
+			Expect(service.HasProvider()).To(BeFalse())
+		})
+
+		It("returns true when a plugin is available", func() {
+			loader.names = []string{"test-plugin"}
+			service = sonic.New(ds, loader, nil)
+			Expect(service.HasProvider()).To(BeTrue())
+		})
+	})
+
+	Describe("GetSonicSimilarTracks", func() {
+		It("returns error when no plugin available", func() {
+			loader.names = nil
+			service = sonic.New(ds, loader, nil)
+			_, err := service.GetSonicSimilarTracks(ctx, "song-1", 10)
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+
+		It("returns error when media file not found", func() {
+			loader.names = []string{"test-plugin"}
+			loader.provider = &mockProvider{}
+			loader.loadOk = true
+			ds.MockedMediaFile = &tests.MockMediaFileRepo{}
+			service = sonic.New(ds, loader, matcher.New(ds))
+			_, err := service.GetSonicSimilarTracks(ctx, "nonexistent", 10)
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("returns matched results from plugin", func() {
+			mf1 := model.MediaFile{ID: "song-1", Title: "Test Song", Artist: "Test Artist"}
+			mf2 := model.MediaFile{ID: "song-2", Title: "Similar Song", Artist: "Test Artist"}
+
+			mockRepo := tests.CreateMockMediaFileRepo()
+			mockRepo.SetData(model.MediaFiles{mf1, mf2})
+			ds.MockedMediaFile = mockRepo
+
+			provider := &mockProvider{
+				similarResults: []sonic.SimilarResult{
+					{Song: agents.Song{ID: "song-2", Name: "Similar Song", Artist: "Test Artist"}, Similarity: 0.85},
+				},
+			}
+			loader.names = []string{"test-plugin"}
+			loader.provider = provider
+			loader.loadOk = true
+
+			service = sonic.New(ds, loader, matcher.New(ds))
+			matches, err := service.GetSonicSimilarTracks(ctx, "song-1", 10)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(matches).To(HaveLen(1))
+			Expect(matches[0].MediaFile.ID).To(Equal("song-2"))
+			Expect(matches[0].Similarity).To(Equal(0.85))
+		})
+	})
+
+	Describe("FindSonicPath", func() {
+		It("returns error when no plugin available", func() {
+			loader.names = nil
+			service = sonic.New(ds, loader, nil)
+			_, err := service.FindSonicPath(ctx, "song-1", "song-2", 25)
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+
+		It("returns error when plugin call fails", func() {
+			mf1 := model.MediaFile{ID: "song-1", Title: "Start", Artist: "Artist"}
+			mf2 := model.MediaFile{ID: "song-2", Title: "End", Artist: "Artist"}
+
+			mockRepo := tests.CreateMockMediaFileRepo()
+			mockRepo.SetData(model.MediaFiles{mf1, mf2})
+			ds.MockedMediaFile = mockRepo
+
+			provider := &mockProvider{pathErr: errors.New("plugin error")}
+			loader.names = []string{"test-plugin"}
+			loader.provider = provider
+			loader.loadOk = true
+
+			service = sonic.New(ds, loader, matcher.New(ds))
+			_, err := service.FindSonicPath(ctx, "song-1", "song-2", 25)
+			Expect(err).To(HaveOccurred())
+		})
+	})
+})

core/storage/local/local.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/djherbis/times"
 	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model/metadata"
@@ -28,7 +29,13 @@ type localStorage struct {
 func newLocalStorage(u url.URL) storage.Storage {
 	newExtractor, ok := extractors[conf.Server.Scanner.Extractor]
 	if !ok || newExtractor == nil {
-		log.Fatal("Extractor not found", "path", conf.Server.Scanner.Extractor)
+		if conf.Server.Scanner.Extractor != consts.DefaultScannerExtractor {
+			log.Warn("Extractor not found, using default", "extractor", conf.Server.Scanner.Extractor, "default", consts.DefaultScannerExtractor)
+		}
+		newExtractor = extractors[consts.DefaultScannerExtractor]
+		if newExtractor == nil {
+			log.Fatal("Default extractor not registered", "extractor", consts.DefaultScannerExtractor)
+		}
 	}
 	isWindowsPath := filepath.VolumeName(u.Host) != ""
 	if u.Scheme == storage.LocalSchemaID && isWindowsPath {

core/storage/local/local_test.go

@@ -10,8 +10,10 @@ import (
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/model/metadata"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -43,6 +45,10 @@ var _ = Describe("LocalStorage", func() {
 	})
 
 	Describe("newLocalStorage", func() {
+		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
+		})
+
 		Context("with valid path", func() {
 			It("should create a localStorage instance with correct path", func() {
 				u, err := url.Parse("file://" + tempDir)
@@ -135,21 +141,40 @@ var _ = Describe("LocalStorage", func() {
 			})
 		})
 
-		Context("with invalid extractor", func() {
-			It("should handle extractor validation correctly", func() {
-				// Note: The actual implementation uses log.Fatal which exits the process,
-				// so we test the normal path where extractors exist
+		Context("when the configured extractor is not registered", func() {
+			var defaultExtractor *mockTestExtractor
+
+			BeforeEach(func() {
+				defaultExtractor = &mockTestExtractor{results: make(map[string]metadata.Info)}
+				RegisterExtractor(consts.DefaultScannerExtractor, func(fs.FS, string) Extractor {
+					return defaultExtractor
+				})
+				DeferCleanup(func() {
+					lock.Lock()
+					delete(extractors, consts.DefaultScannerExtractor)
+					lock.Unlock()
+				})
+			})
+
+			It("falls back to the default extractor instead of crashing", func() {
+				conf.Server.Scanner.Extractor = "nonexistent-extractor"
 
 				u, err := url.Parse("file://" + tempDir)
 				Expect(err).ToNot(HaveOccurred())
 
 				storage := newLocalStorage(*u)
-				Expect(storage).ToNot(BeNil())
+				ls, ok := storage.(*localStorage)
+				Expect(ok).To(BeTrue())
+				Expect(ls.extractor).To(BeIdenticalTo(defaultExtractor))
 			})
 		})
 	})
 
 	Describe("localStorage.FS", func() {
+		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
+		})
+
 		Context("with existing directory", func() {
 			It("should return a localFS instance", func() {
 				u, err := url.Parse("file://" + tempDir)
@@ -183,6 +208,7 @@ var _ = Describe("LocalStorage", func() {
 		var testFile string
 
 		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
 			// Create a test file
 			testFile = filepath.Join(tempDir, "test.mp3")
 			err := os.WriteFile(testFile, []byte("test data"), 0600)
@@ -364,6 +390,7 @@ var _ = Describe("LocalStorage", func() {
 
 	Describe("Storage registration", func() {
 		It("should register localStorage for file scheme", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
 			// This tests the init() function indirectly
 			storage, err := storage.For("file://" + tempDir)
 			Expect(err).ToNot(HaveOccurred())

core/storage/storage_test.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -54,6 +55,7 @@ var _ = Describe("Storage", func() {
 			Expect(s.(*fakeLocalStorage).u.Path).To(Equal("/tmp"))
 		})
 		It("should return a file implementation for a relative folder", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage)")
 			s, err := For("tmp")
 			Expect(err).ToNot(HaveOccurred())
 			cwd, _ := os.Getwd()

core/stream/codec.go

@@ -75,3 +75,16 @@ func codecMaxSampleRate(codec string) int {
 	}
 	return 0
 }
+
+// codecMaxChannels returns the hard maximum number of audio channels a codec
+// supports. Returns 0 if the codec has no hard limit (or is unknown), in which
+// case the source/profile constraints applied upstream are authoritative.
+func codecMaxChannels(codec string) int {
+	switch strings.ToLower(codec) {
+	case "mp3":
+		return 2
+	case "opus":
+		return 8
+	}
+	return 0
+}

core/stream/codec_test.go

@@ -66,4 +66,26 @@ var _ = Describe("Codec", func() {
 			Expect(normalizeProbeCodec("DSD_LSBF_PLANAR")).To(Equal("dsd"))
 		})
 	})
+
+	Describe("codecMaxChannels", func() {
+		It("returns 2 for mp3", func() {
+			Expect(codecMaxChannels("mp3")).To(Equal(2))
+		})
+
+		It("returns 8 for opus", func() {
+			Expect(codecMaxChannels("opus")).To(Equal(8))
+		})
+
+		It("is case-insensitive", func() {
+			Expect(codecMaxChannels("MP3")).To(Equal(2))
+			Expect(codecMaxChannels("Opus")).To(Equal(8))
+		})
+
+		It("returns 0 for codecs with no hard limit", func() {
+			Expect(codecMaxChannels("aac")).To(Equal(0))
+			Expect(codecMaxChannels("flac")).To(Equal(0))
+			Expect(codecMaxChannels("vorbis")).To(Equal(0))
+			Expect(codecMaxChannels("")).To(Equal(0))
+		})
+	})
 })

core/stream/decider.go

@@ -44,10 +44,14 @@ func (s *deciderService) MakeDecision(ctx context.Context, mf *model.MediaFile,
 
 	var probe *ffmpeg.AudioProbeResult
 	if !opts.SkipProbe {
-		var err error
-		probe, err = s.ensureProbed(ctx, mf)
-		if err != nil {
-			return nil, err
+		if !s.ff.IsProbeAvailable() {
+			log.Debug(ctx, "ffprobe not available, using tag metadata for transcode decision", "mediaID", mf.ID)
+		} else {
+			var err error
+			probe, err = s.ensureProbed(ctx, mf)
+			if err != nil {
+				return nil, err
+			}
 		}
 	}
 
@@ -195,6 +199,17 @@ func parseProbeData(data string) (*ffmpeg.AudioProbeResult, error) {
 	return &result, nil
 }
 
+// matchesPCMWAVBridge bridges Navidrome's internal "pcm" codec name with the
+// "wav" codec name that browsers use to advertise audio/wav support. The match
+// is scoped to WAV-container sources so AIFF files (which also normalize to
+// codec "pcm" but use a different container) cannot false-match a codec-only
+// ["wav"] profile.
+func matchesPCMWAVBridge(src *Details, profile *DirectPlayProfile) bool {
+	return strings.EqualFold(src.Codec, "pcm") &&
+		strings.EqualFold(src.Container, "wav") &&
+		containsIgnoreCase(profile.AudioCodecs, "wav")
+}
+
 // checkDirectPlayProfile returns "" if the profile matches (direct play OK),
 // or a typed reason string if it doesn't match.
 func (s *deciderService) checkDirectPlayProfile(src *Details, profile *DirectPlayProfile, clientInfo *ClientInfo) string {
@@ -205,17 +220,17 @@ func (s *deciderService) checkDirectPlayProfile(src *Details, profile *DirectPla
 
 	// Check container
 	if len(profile.Containers) > 0 && !matchesContainer(src.Container, profile.Containers) {
-		return "container not supported"
+		return fmt.Sprintf("container '%s' not supported by profile %s", src.Container, profile)
 	}
 
 	// Check codec
-	if len(profile.AudioCodecs) > 0 && !matchesCodec(src.Codec, profile.AudioCodecs) {
-		return "audio codec not supported"
+	if len(profile.AudioCodecs) > 0 && !matchesCodec(src.Codec, profile.AudioCodecs) && !matchesPCMWAVBridge(src, profile) {
+		return fmt.Sprintf("audio codec '%s' not supported by profile %s", src.Codec, profile)
 	}
 
 	// Check channels
 	if profile.MaxAudioChannels > 0 && src.Channels > profile.MaxAudioChannels {
-		return "audio channels not supported"
+		return fmt.Sprintf("audio channels %d not supported by profile %s (max %d)", src.Channels, profile, profile.MaxAudioChannels)
 	}
 
 	// Check codec-specific limitations
@@ -279,14 +294,19 @@ func (s *deciderService) computeTranscodedStream(ctx context.Context, src *Detai
 	if maxRate := codecMaxSampleRate(ts.Codec); maxRate > 0 && ts.SampleRate > maxRate {
 		ts.SampleRate = maxRate
 	}
+	if maxCh := codecMaxChannels(ts.Codec); maxCh > 0 && ts.Channels > maxCh {
+		ts.Channels = maxCh
+	}
 
 	// Determine target bitrate (all in kbps)
 	if ok := s.computeBitrate(ctx, src, targetFormat, targetIsLossless, clientInfo, ts); !ok {
 		return nil, ""
 	}
 
-	// Apply MaxAudioChannels from the transcoding profile
-	if profile.MaxAudioChannels > 0 && src.Channels > profile.MaxAudioChannels {
+	// Apply MaxAudioChannels from the transcoding profile. Compare against the
+	// already-clamped ts.Channels (not src.Channels) so the codec hard limit
+	// applied above is never raised by a looser profile setting.
+	if profile.MaxAudioChannels > 0 && ts.Channels > profile.MaxAudioChannels {
 		ts.Channels = profile.MaxAudioChannels
 	}
 

core/stream/decider_test.go

@@ -76,7 +76,10 @@ var _ = Describe("Decider", func() {
 				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(decision.CanDirectPlay).To(BeFalse())
-				Expect(decision.TranscodeReasons).To(ContainElement("container not supported"))
+				Expect(decision.TranscodeReasons).To(ContainElement(And(
+					ContainSubstring("container 'flac' not supported"),
+					ContainSubstring("[mp3]"),
+				)))
 			})
 
 			It("rejects direct play when codec doesn't match", func() {
@@ -89,7 +92,10 @@ var _ = Describe("Decider", func() {
 				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(decision.CanDirectPlay).To(BeFalse())
-				Expect(decision.TranscodeReasons).To(ContainElement("audio codec not supported"))
+				Expect(decision.TranscodeReasons).To(ContainElement(And(
+					ContainSubstring("audio codec 'alac' not supported"),
+					ContainSubstring("[m4a/aac]"),
+				)))
 			})
 
 			It("rejects direct play when channels exceed limit", func() {
@@ -102,7 +108,44 @@ var _ = Describe("Decider", func() {
 				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(decision.CanDirectPlay).To(BeFalse())
-				Expect(decision.TranscodeReasons).To(ContainElement("audio channels not supported"))
+				Expect(decision.TranscodeReasons).To(ContainElement(And(
+					ContainSubstring("audio channels 6 not supported"),
+					ContainSubstring("[flac]"),
+					ContainSubstring("(max 2)"),
+				)))
+			})
+
+			It("accepts WAV source against a wav codec profile (pcm->wav bridge)", func() {
+				// ffprobe normalizes PCM variants (pcm_s16le etc) to codec "pcm", but
+				// browsers advertise WAV support as audioCodecs:["wav"] via audio/wav MIME.
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "wav", Codec: "pcm", BitRate: 1411, Channels: 2})
+				ci := &ClientInfo{
+					DirectPlayProfiles: []DirectPlayProfile{
+						{Containers: []string{"wav"}, AudioCodecs: []string{"wav"}, Protocols: []string{ProtocolHTTP}},
+					},
+				}
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanDirectPlay).To(BeTrue())
+			})
+
+			It("does not accept AIFF (pcm in non-wav container) against a wav codec profile", func() {
+				// AIFF files also normalize to codec="pcm" but use container="aiff".
+				// Without the container guard they would falsely match a codec-only
+				// ["wav"] profile and be direct-played as if they were WAV.
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "aiff", Codec: "pcm", BitRate: 1411, Channels: 2})
+				ci := &ClientInfo{
+					DirectPlayProfiles: []DirectPlayProfile{
+						{AudioCodecs: []string{"wav"}, Protocols: []string{ProtocolHTTP}},
+					},
+					TranscodingProfiles: []Profile{
+						{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP},
+					},
+				}
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanDirectPlay).To(BeFalse())
+				Expect(decision.TranscodeReasons).To(ContainElement(ContainSubstring("audio codec 'pcm'")))
 			})
 
 			It("handles container aliases (aac -> m4a)", func() {
@@ -216,7 +259,10 @@ var _ = Describe("Decider", func() {
 				Expect(decision.CanTranscode).To(BeTrue())
 				Expect(decision.TargetFormat).To(Equal("mp3"))
 				Expect(decision.TargetBitrate).To(Equal(256)) // kbps
-				Expect(decision.TranscodeReasons).To(ContainElement("container not supported"))
+				Expect(decision.TranscodeReasons).To(ContainElement(And(
+					ContainSubstring("container 'flac' not supported"),
+					ContainSubstring("[mp3]"),
+				)))
 			})
 
 			It("rejects lossy to lossless transcoding", func() {
@@ -724,6 +770,73 @@ var _ = Describe("Decider", func() {
 			})
 		})
 
+		Context("Codec channel limits", func() {
+			It("clamps 6-channel FLAC to 2 channels when transcoding to MP3", func() {
+				// Regression test for #5336: ffmpeg's mp3 encoder rejects >2 channels.
+				// The decider must clamp to the codec's hard limit even when no
+				// transcoding profile MaxAudioChannels is configured.
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 6, SampleRate: 44100, BitDepth: 16})
+				ci := &ClientInfo{
+					MaxTranscodingAudioBitrate: 320,
+					TranscodingProfiles: []Profile{
+						{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP},
+					},
+				}
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanTranscode).To(BeTrue())
+				Expect(decision.TargetFormat).To(Equal("mp3"))
+				Expect(decision.TranscodeStream.Channels).To(Equal(2))
+				Expect(decision.TargetChannels).To(Equal(2))
+			})
+
+			It("honors a stricter profile MaxAudioChannels over the codec clamp", func() {
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 6, SampleRate: 44100, BitDepth: 16})
+				ci := &ClientInfo{
+					MaxTranscodingAudioBitrate: 320,
+					TranscodingProfiles: []Profile{
+						{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP, MaxAudioChannels: 1},
+					},
+				}
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanTranscode).To(BeTrue())
+				Expect(decision.TranscodeStream.Channels).To(Equal(1))
+				Expect(decision.TargetChannels).To(Equal(1))
+			})
+
+			It("applies the codec clamp when the profile limit is looser", func() {
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 6, SampleRate: 44100, BitDepth: 16})
+				ci := &ClientInfo{
+					MaxTranscodingAudioBitrate: 320,
+					TranscodingProfiles: []Profile{
+						{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP, MaxAudioChannels: 4},
+					},
+				}
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanTranscode).To(BeTrue())
+				Expect(decision.TranscodeStream.Channels).To(Equal(2))
+				Expect(decision.TargetChannels).To(Equal(2))
+			})
+
+			It("passes channels through unchanged for codecs with no hard limit", func() {
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 6, SampleRate: 44100, BitDepth: 16})
+				ci := &ClientInfo{
+					MaxTranscodingAudioBitrate: 320,
+					TranscodingProfiles: []Profile{
+						{Container: "m4a", AudioCodec: "aac", Protocol: ProtocolHTTP},
+					},
+				}
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanTranscode).To(BeTrue())
+				Expect(decision.TargetFormat).To(Equal("aac"))
+				Expect(decision.TranscodeStream.Channels).To(Equal(6))
+				Expect(decision.TargetChannels).To(Equal(6))
+			})
+		})
+
 		Context("Probe-based lossless detection", func() {
 			It("uses probe codec name for lossless detection", func() {
 				// WavPack files: ffprobe reports codec as "wavpack", suffix is ".wv"
@@ -901,9 +1014,12 @@ var _ = Describe("Decider", func() {
 				Expect(err).ToNot(HaveOccurred())
 				Expect(decision.CanDirectPlay).To(BeFalse())
 				Expect(decision.TranscodeReasons).To(HaveLen(3))
-				Expect(decision.TranscodeReasons[0]).To(Equal("container not supported"))
-				Expect(decision.TranscodeReasons[1]).To(Equal("container not supported"))
-				Expect(decision.TranscodeReasons[2]).To(Equal("container not supported"))
+				Expect(decision.TranscodeReasons[0]).To(ContainSubstring("container 'ogg' not supported"))
+				Expect(decision.TranscodeReasons[0]).To(ContainSubstring("[flac]"))
+				Expect(decision.TranscodeReasons[1]).To(ContainSubstring("container 'ogg' not supported"))
+				Expect(decision.TranscodeReasons[1]).To(ContainSubstring("[mp3/mp3]"))
+				Expect(decision.TranscodeReasons[2]).To(ContainSubstring("container 'ogg' not supported"))
+				Expect(decision.TranscodeReasons[2]).To(ContainSubstring("[m4a,mp4/aac]"))
 			})
 		})
 
@@ -1115,6 +1231,7 @@ var _ = Describe("Decider", func() {
 				Expect(bitrate).To(Equal(fallbackBitrate))
 			})
 		})
+
 	})
 
 	Describe("ensureProbed", func() {

core/stream/types.go

@@ -2,6 +2,7 @@ package stream
 
 import (
 	"errors"
+	"strings"
 	"time"
 )
 
@@ -47,6 +48,18 @@ type DirectPlayProfile struct {
 	MaxAudioChannels int
 }
 
+func (p DirectPlayProfile) String() string {
+	containers := strings.Join(p.Containers, ",")
+	if containers == "" {
+		containers = "*"
+	}
+	codecs := strings.Join(p.AudioCodecs, ",")
+	if codecs == "" {
+		return "[" + containers + "]"
+	}
+	return "[" + containers + "/" + codecs + "]"
+}
+
 // Profile describes a transcoding target the client supports
 type Profile struct {
 	Container        string