fix: address review feedback on authProvider

Remove unused vi import from test file. Use Number() || 0 instead of parseInt with string fallback to handle corrupted sessionStorage values that would produce NaN.
style: format authProvider test with prettier
2026-09-09 12:12:49 -04:00 · 2026-05-03 13:50:15 -04:00 · 2026-05-03 13:35:34 -04:00 · 2026-05-03 13:35:04 -04:00 · 2026-05-03 12:34:00 -04:00 · 2026-05-03 11:26:07 -04:00
654 changed files with 46599 additions and 10131 deletions
@@ -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.1.1-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
@@ -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.1.1-1"
+			"NODE_VERSION": "v24"
 		}
 	},
 	"workspaceMount": "",
@@ -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
@@ -14,8 +14,6 @@ concurrency:
  cancel-in-progress: true

 env:
-  CROSS_TAGLIB_VERSION: "2.1.1-2"
-  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 -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 ]
@@ -221,7 +288,7 @@ jobs:
          hub_password: ${{ secrets.DOCKER_HUB_PASSWORD }}

      - name: Build Binaries
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
        with:
          context: .
          file: Dockerfile
@@ -232,10 +299,9 @@ 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@v6
+        uses: actions/upload-artifact@v7
        with:
          name: navidrome-${{ env.PLATFORM }}
          path: ./output
@@ -244,7 +310,7 @@ jobs:
      - name: Build and push image by digest
        id: push-image
        if: env.IS_LINUX == 'true' && env.IS_DOCKER_PUSH_CONFIGURED == 'true' && env.IS_ARMV5 == 'false'
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
        with:
          context: .
          file: Dockerfile
@@ -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
@@ -266,7 +331,7 @@ jobs:
          touch "/tmp/digests/${digest#sha256:}"          

      - name: Upload digest
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
        if: env.IS_LINUX == 'true' && env.IS_DOCKER_PUSH_CONFIGURED == 'true' && env.IS_ARMV5 == 'false'
        with:
          name: digests-${{ env.PLATFORM }}
@@ -288,7 +353,7 @@ jobs:
      - uses: actions/checkout@v6

      - name: Download digests
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
        with:
          path: /tmp/digests
          pattern: digests-*
@@ -322,7 +387,7 @@ jobs:
      - uses: actions/checkout@v6

      - name: Download digests
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
        with:
          path: /tmp/digests
          pattern: digests-*
@@ -338,7 +403,7 @@ jobs:
          hub_password: ${{ secrets.DOCKER_HUB_PASSWORD }}

      - name: Create manifest list and push to Docker Hub
-        uses: nick-fields/retry@v3
+        uses: nick-fields/retry@v4
        with:
          timeout_minutes: 5
          max_attempts: 3
@@ -374,7 +439,7 @@ jobs:
    steps:
      - uses: actions/checkout@v6

-      - uses: actions/download-artifact@v7
+      - uses: actions/download-artifact@v8
        with:
          path: ./binaries
          pattern: navidrome-windows*
@@ -393,7 +458,7 @@ jobs:
          du -h binaries/msi/*.msi

      - name: Upload MSI files
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
        with:
          name: navidrome-windows-installers
          path: binaries/msi/*.msi
@@ -411,7 +476,7 @@ jobs:
          fetch-depth: 0
          fetch-tags: true

-      - uses: actions/download-artifact@v7
+      - uses: actions/download-artifact@v8
        with:
          path: ./binaries
          pattern: navidrome-*
@@ -424,7 +489,7 @@ jobs:
        run: echo 'RELEASE_FLAGS=--skip=publish --snapshot' >> $GITHUB_ENV

      - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@v6
+        uses: goreleaser/goreleaser-action@v7
        with:
          version: '~> v2'
          args: "release --clean -f release/goreleaser.yml ${{ env.RELEASE_FLAGS }}"
@@ -437,7 +502,7 @@ jobs:
          rm ./dist/*.tar.gz ./dist/*.zip

      - name: Upload all-packages artifact
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
        with:
          name: packages
          path: dist/navidrome_0*
@@ -460,13 +525,13 @@ jobs:
        item: ${{ fromJson(needs.release.outputs.package_list) }}
    steps:
      - name: Download all-packages artifact
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
        with:
          name: packages
          path: ./dist

      - name: Upload all-packages artifact
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
        with:
          name: navidrome_linux_${{ matrix.item }}
          path: dist/navidrome_0*_linux_${{ matrix.item }}
@@ -37,4 +37,5 @@ AGENTS.md
 *.wasm
 *.ndp
 openspec/
-go.work*
+go.work*
+.worktrees/
@@ -2,6 +2,7 @@ version: "2"
 run:
  build-tags:
    - netgo
+    - sqlite_fts5
 linters:
  enable:
    - asasalint
@@ -39,6 +40,11 @@ linters:
      enable:
        - nilness
  exclusions:
+    rules:
+      - linters:
+          - gosec
+        path: _test\.go
+        text: "G703"
    generated: lax
    presets:
      - comments
@@ -49,6 +55,7 @@ linters:
      - third_party$
      - builtin$
      - examples$
+      - node_modules
 formatters:
  exclusions:
    generated: lax
@@ -56,3 +63,4 @@ formatters:
      - third_party$
      - builtin$
      - examples$
+      - node_modules
@@ -38,7 +38,7 @@ Before submitting a pull request, ensure that you go through the following:
 ### Commit Conventions
 Each commit message must adhere to the following format:
 ```
-<type>(scope): <description> - <issue number>
+<type>(scope): <description>

 [optional body]
 ```
@@ -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.1.1-2
-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.
@@ -109,7 +125,7 @@ RUN --mount=type=bind,source=. \
        export EXT=".exe"
    fi

-    go build -tags=netgo -ldflags="${LD_EXTRA} -w -s \
+    go build -tags=netgo,sqlite_fts5 -ldflags="${LD_EXTRA} -w -s \
        -X github.com/navidrome/navidrome/consts.gitSha=${GIT_SHA} \
        -X github.com/navidrome/navidrome/consts.gitTag=${GIT_TAG}" \
        -o /out/navidrome${EXT} .
@@ -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"]

@@ -1,8 +1,10 @@
 GO_VERSION=$(shell grep "^go " go.mod | cut -f 2 -d ' ')
 NODE_VERSION=$(shell cat .nvmrc)

+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)","")
@@ -18,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.1.1-2
-GOLANGCI_LINT_VERSION ?= v2.9.0
+GOLANGCI_LINT_VERSION ?= v2.12.0

 UI_SRC_FILES := $(shell find ui -type f -not -path "ui/build/*" -not -path "ui/node_modules/*")

@@ -46,12 +46,12 @@ stop: ##@Development Stop development servers (UI and backend)
 .PHONY: stop

 watch: ##@Development Start Go tests in watch mode (re-run when code changes)
-	go tool ginkgo watch -tags=netgo -notify ./...
+	go tool ginkgo watch -tags=$(GO_BUILD_TAGS) -notify ./...
 .PHONY: watch

 PKG ?= ./...
 test: ##@Development Run Go tests. Use PKG variable to specify packages to test, e.g. make test PKG=./server
-	go test -tags netgo $(PKG)
+	go test -tags $(GO_BUILD_TAGS) $(PKG)
 .PHONY: test

 test-ndpgen: ##@Development Run tests for ndpgen plugin
@@ -62,7 +62,7 @@ testall: test test-ndpgen test-i18n test-js ##@Development Run Go and JS tests
 .PHONY: testall

 test-race: ##@Development Run Go tests with race detector
-	go test -tags netgo -race -shuffle=on  $(PKG)
+	go test -tags $(GO_BUILD_TAGS) -race -shuffle=on  $(PKG)
 .PHONY: test-race

 test-js: ##@Development Run JS tests
@@ -75,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..."; \
@@ -93,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
@@ -108,7 +108,7 @@ format: ##@Development Format code
 .PHONY: format

 wire: check_go_env ##@Development Update Dependency Injection
-	go tool wire gen -tags=netgo ./...
+	go tool wire gen -tags="$$(echo '$(GO_BUILD_TAGS)' | tr ',' ' ')" ./...
 .PHONY: wire

 gen: check_go_env ##@Development Run go generate for code generation
@@ -144,14 +144,14 @@ setup-git: ##@Development Setup Git hooks (pre-commit and pre-push)
 .PHONY: setup-git

 build: check_go_env buildjs ##@Build Build the project
-	go build -ldflags="-X github.com/navidrome/navidrome/consts.gitSha=$(GIT_SHA) -X github.com/navidrome/navidrome/consts.gitTag=$(GIT_TAG)" -tags=netgo
+	go build -ldflags="-X github.com/navidrome/navidrome/consts.gitSha=$(GIT_SHA) -X github.com/navidrome/navidrome/consts.gitTag=$(GIT_TAG)" -tags=$(GO_BUILD_TAGS)
 .PHONY: build

 buildall: deprecated build
 .PHONY: buildall

 debug-build: check_go_env buildjs ##@Build Build the project (with remote debug on)
-	go build -gcflags="all=-N -l" -ldflags="-X github.com/navidrome/navidrome/consts.gitSha=$(GIT_SHA) -X github.com/navidrome/navidrome/consts.gitTag=$(GIT_TAG)" -tags=netgo
+	go build -gcflags="all=-N -l" -ldflags="-X github.com/navidrome/navidrome/consts.gitSha=$(GIT_SHA) -X github.com/navidrome/navidrome/consts.gitTag=$(GIT_TAG)" -tags=$(GO_BUILD_TAGS)
 .PHONY: debug-build

 buildjs: check_node_env ui/build/index.html ##@Build Build only frontend
@@ -176,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

@@ -188,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

@@ -201,8 +199,8 @@ docker-msi: ##@Cross_Compilation Build MSI installer for Windows
 	@du -h binaries/msi/*.msi
 .PHONY: docker-msi

-run-docker: ##@Development Run a Navidrome Docker image. Usage: make run-docker tag=<tag>
-	@if [ -z "$(tag)" ]; then echo "Usage: make run-docker tag=<tag>"; exit 1; fi
+docker-run: ##@Development Run a Navidrome Docker image. Usage: make docker-run tag=<tag>
+	@if [ -z "$(tag)" ]; then echo "Usage: make docker-run tag=<tag>"; exit 1; fi
 	@TAG_DIR="tmp/$$(echo '$(tag)' | tr '/:' '_')"; mkdir -p "$$TAG_DIR"; \
    VOLUMES="-v $(PWD)/$$TAG_DIR:/data"; \
 	if [ -f navidrome.toml ]; then \
@@ -213,7 +211,7 @@ run-docker: ##@Development Run a Navidrome Docker image. Usage: make run-docker
 	  	fi; \
 	fi; \
 	echo "Running: docker run --rm -p 4533:4533 $$VOLUMES $(tag)"; docker run --rm -p 4533:4533 $$VOLUMES $(tag)
-.PHONY: run-docker
+.PHONY: docker-run

 package: docker-build ##@Cross_Compilation Create binaries and packages for ALL supported platforms
 	@if [ -z `which goreleaser` ]; then echo "Please install goreleaser first: https://goreleaser.com/install/"; exit 1; fi
@@ -232,6 +230,39 @@ get-music: ##@Development Download some free music from Navidrome's demo instanc
 .PHONY: get-music


+##########################################
+#### Worktrees
+
+WORKTREES_DIR := .worktrees
+
+wt: check_go_env ##@Worktrees Create and setup a git worktree. Usage: make wt name=feature-name [go=1]
+	@if [ -z "${name}" ]; then echo "Usage: make wt name=<branch-name> [go=1]"; exit 1; fi
+	@mkdir -p $(WORKTREES_DIR)
+	@echo "Creating worktree for branch '${name}'..."
+	@git worktree add $(WORKTREES_DIR)/${name} -b ${name} 2>/dev/null || \
+		git worktree add $(WORKTREES_DIR)/${name} ${name}
+	@if [ -n "${go}" ]; then \
+		./scripts/setup-worktree.sh $(WORKTREES_DIR)/${name} --go-only; \
+	else \
+		./scripts/setup-worktree.sh $(WORKTREES_DIR)/${name}; \
+	fi
+	@echo "\nWorktree ready at $(WORKTREES_DIR)/${name}"
+	@echo "  cd $(WORKTREES_DIR)/${name}"
+.PHONY: wt
+
+rm-wt: ##@Worktrees Remove a git worktree. Usage: make rm-wt name=feature-name
+	@if [ -z "${name}" ]; then echo "Usage: make rm-wt name=<branch-name>"; exit 1; fi
+	@if [ ! -d "$(WORKTREES_DIR)/${name}" ]; then echo "Worktree '${name}' not found in $(WORKTREES_DIR)/"; exit 1; fi
+	@echo "Removing worktree '${name}'..."
+	@git worktree remove --force $(WORKTREES_DIR)/${name}
+	@echo "Worktree '${name}' removed."
+	@echo "Note: branch '${name}' still exists. Delete it with: git branch -D ${name}"
+.PHONY: rm-wt
+
+ls-wt: ##@Worktrees List all active git worktrees
+	@git worktree list
+.PHONY: ls-wt
+
 ##########################################
 #### Miscellaneous

@@ -10,7 +10,7 @@ import (
 	"sync"
 	"time"

-	"github.com/lestrrat-go/jwx/v2/jwt"
+	"github.com/lestrrat-go/jwx/v3/jwt"
 	"github.com/navidrome/navidrome/log"
 )

@@ -65,7 +65,7 @@ func (c *client) getJWT(ctx context.Context) (string, error) {
 	}

 	type authResponse struct {
-		JWT string `json:"jwt"`
+		JWT string `json:"jwt"` //nolint:gosec
 	}

 	var result authResponse
@@ -84,8 +84,8 @@ func (c *client) getJWT(ctx context.Context) (string, error) {
 	}

 	// Calculate TTL with a 1-minute buffer for clock skew and network delays
-	expiresAt := token.Expiration()
-	if expiresAt.IsZero() {
+	expiresAt, ok := token.Expiration()
+	if !ok || expiresAt.IsZero() {
 		return "", errors.New("deezer: JWT token has no expiration time")
 	}

@@ -9,7 +9,7 @@ import (
 	"sync"
 	"time"

-	"github.com/lestrrat-go/jwx/v2/jwt"
+	"github.com/lestrrat-go/jwx/v3/jwt"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -179,7 +179,8 @@ var _ = Describe("JWT Authentication", func() {
 				Expect(err).To(BeNil())

 				// Verify token has no expiration
-				Expect(testToken.Expiration().IsZero()).To(BeTrue())
+				_, hasExp := testToken.Expiration()
+				Expect(hasExp).To(BeFalse())

 				testJWT, err := jwt.Sign(testToken, jwt.WithInsecureNoSignature())
 				Expect(err).To(BeNil())
@@ -20,6 +20,7 @@ import (
 	"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"
@@ -43,10 +44,34 @@ func (e extractor) Parse(files ...string) (map[string]metadata.Info, error) {
 }

 func (e extractor) Version() string {
-	return "go-taglib (TagLib 2.1.1 WASM)"
+	bi, ok := debug.ReadBuildInfo()
+	if ok {
+		for _, dep := range bi.Deps {
+			if dep.Path == "go.senan.xyz/taglib" {
+				if dep.Replace != nil {
+					return dep.Replace.Version
+				}
+				return dep.Version
+			}
+		}
+	}
+	return "unknown"
 }

-func (e extractor) extractMetadata(filePath string) (*metadata.Info, error) {
+func (e extractor) extractMetadata(filePath string) (info *metadata.Info, err error) {
+	// Recover from panics in the WASM runtime that can occur during any taglib
+	// operation (opening, reading tags, or reading properties). This catches crashes
+	// from malformed files or WASM runtime issues (e.g., wazero mmap failures on
+	// hardened systems with MemoryDenyWriteExecute=true).
+	debug.SetPanicOnFault(true)
+	defer func() {
+		if r := recover(); r != nil {
+			log.Error("gotaglib: WASM runtime panic reading file. Skipping", "filePath", filePath, "panic", r)
+			debug.PrintStack()
+			err = fmt.Errorf("WASM runtime panic: %v", r)
+		}
+	}()
+
 	f, close, err := e.openFile(filePath)
 	if err != nil {
 		log.Warn("gotaglib: Error reading metadata from file. Skipping", "filePath", filePath, err)
@@ -65,6 +90,7 @@ func (e extractor) extractMetadata(filePath string) (*metadata.Info, error) {
 		Channels:   int(props.Channels),
 		SampleRate: int(props.SampleRate),
 		BitDepth:   int(props.BitsPerSample),
+		Codec:      props.Codec,
 	}

 	// Convert normalized tags to lowercase keys (go-taglib returns UPPERCASE keys)
@@ -99,16 +125,6 @@ func (e extractor) extractMetadata(filePath string) (*metadata.Info, error) {
 // openFile opens the file at filePath using the extractor's filesystem.
 // It returns a TagLib File handle and a cleanup function to close resources.
 func (e extractor) openFile(filePath string) (f *taglib.File, closeFunc func(), err error) {
-	// Recover from panics in the WASM runtime (e.g., wazero failing to mmap executable memory
-	// on hardened systems like NixOS with MemoryDenyWriteExecute=true)
-	debug.SetPanicOnFault(true)
-	defer func() {
-		if r := recover(); r != nil {
-			log.Error("WASM runtime panic: This may be caused by a hardened system that blocks executable memory mapping.", "file", filePath, "panic", r)
-			err = fmt.Errorf("WASM runtime panic (hardened system?): %v", r)
-		}
-	}()
-
 	// Open the file from the filesystem
 	file, err := e.fs.Open(filePath)
 	if err != nil {
@@ -279,4 +295,7 @@ func init() {
 	local.RegisterExtractor("taglib", func(fsys fs.FS, baseDir string) local.Extractor {
 		return &extractor{fsys}
 	})
+	conf.AddHook(func() {
+		log.Debug("go-taglib version", "version", extractor{}.Version())
+	})
 }
@@ -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")
@@ -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 {
@@ -110,7 +110,7 @@ func (s *Router) callback(w http.ResponseWriter, r *http.Request) {
 	if err != nil {
 		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
 		w.WriteHeader(http.StatusBadRequest)
-		_, _ = w.Write([]byte("An error occurred while authorizing with Last.fm. \n\nRequest ID: " + middleware.GetReqID(ctx)))
+		_, _ = w.Write([]byte("An error occurred while authorizing with Last.fm. \n\nRequest ID: " + middleware.GetReqID(ctx))) //nolint:gosec
 		return
 	}

@@ -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 {
@@ -57,7 +57,7 @@ type listenBrainzResponse struct {
 }

 type listenBrainzRequest struct {
-	ApiKey string
+	ApiKey string //nolint:gosec
 	Body   listenBrainzRequestBody
 }

@@ -1,116 +0,0 @@
-package spotify
-
-import (
-	"context"
-	"encoding/base64"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"strconv"
-	"strings"
-
-	"github.com/navidrome/navidrome/log"
-)
-
-const apiBaseUrl = "https://api.spotify.com/v1/"
-
-var (
-	ErrNotFound = errors.New("spotify: not found")
-)
-
-type httpDoer interface {
-	Do(req *http.Request) (*http.Response, error)
-}
-
-func newClient(id, secret string, hc httpDoer) *client {
-	return &client{id, secret, hc}
-}
-
-type client struct {
-	id     string
-	secret string
-	hc     httpDoer
-}
-
-func (c *client) searchArtists(ctx context.Context, name string, limit int) ([]Artist, error) {
-	token, err := c.authorize(ctx)
-	if err != nil {
-		return nil, err
-	}
-
-	params := url.Values{}
-	params.Add("type", "artist")
-	params.Add("q", name)
-	params.Add("offset", "0")
-	params.Add("limit", strconv.Itoa(limit))
-	req, _ := http.NewRequestWithContext(ctx, "GET", apiBaseUrl+"search", nil)
-	req.URL.RawQuery = params.Encode()
-	req.Header.Add("Authorization", "Bearer "+token)
-
-	var results SearchResults
-	err = c.makeRequest(req, &results)
-	if err != nil {
-		return nil, err
-	}
-
-	if len(results.Artists.Items) == 0 {
-		return nil, ErrNotFound
-	}
-	return results.Artists.Items, err
-}
-
-func (c *client) authorize(ctx context.Context) (string, error) {
-	payload := url.Values{}
-	payload.Add("grant_type", "client_credentials")
-
-	encodePayload := payload.Encode()
-	req, _ := http.NewRequestWithContext(ctx, "POST", "https://accounts.spotify.com/api/token", strings.NewReader(encodePayload))
-	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Add("Content-Length", strconv.Itoa(len(encodePayload)))
-	auth := c.id + ":" + c.secret
-	req.Header.Add("Authorization", "Basic "+base64.StdEncoding.EncodeToString([]byte(auth)))
-
-	response := map[string]any{}
-	err := c.makeRequest(req, &response)
-	if err != nil {
-		return "", err
-	}
-
-	if v, ok := response["access_token"]; ok {
-		return v.(string), nil
-	}
-	log.Error(ctx, "Invalid spotify response", "resp", response)
-	return "", errors.New("invalid response")
-}
-
-func (c *client) makeRequest(req *http.Request, response any) error {
-	log.Trace(req.Context(), fmt.Sprintf("Sending Spotify %s request", req.Method), "url", req.URL)
-	resp, err := c.hc.Do(req)
-	if err != nil {
-		return err
-	}
-
-	defer resp.Body.Close()
-	data, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return err
-	}
-
-	if resp.StatusCode != 200 {
-		return c.parseError(data)
-	}
-
-	return json.Unmarshal(data, response)
-}
-
-func (c *client) parseError(data []byte) error {
-	var e Error
-	err := json.Unmarshal(data, &e)
-	if err != nil {
-		return err
-	}
-	return fmt.Errorf("spotify error(%s): %s", e.Code, e.Message)
-}
@@ -1,131 +0,0 @@
-package spotify
-
-import (
-	"bytes"
-	"context"
-	"io"
-	"net/http"
-	"os"
-
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("client", func() {
-	var httpClient *fakeHttpClient
-	var client *client
-
-	BeforeEach(func() {
-		httpClient = &fakeHttpClient{}
-		client = newClient("SPOTIFY_ID", "SPOTIFY_SECRET", httpClient)
-	})
-
-	Describe("ArtistImages", func() {
-		It("returns artist images from a successful request", func() {
-			f, _ := os.Open("tests/fixtures/spotify.search.artist.json")
-			httpClient.mock("https://api.spotify.com/v1/search", http.Response{Body: f, StatusCode: 200})
-			httpClient.mock("https://accounts.spotify.com/api/token", http.Response{
-				StatusCode: 200,
-				Body:       io.NopCloser(bytes.NewBufferString(`{"access_token": "NEW_ACCESS_TOKEN","token_type": "Bearer","expires_in": 3600}`)),
-			})
-
-			artists, err := client.searchArtists(context.TODO(), "U2", 10)
-			Expect(err).To(BeNil())
-			Expect(artists).To(HaveLen(20))
-			Expect(artists[0].Popularity).To(Equal(82))
-
-			images := artists[0].Images
-			Expect(images).To(HaveLen(3))
-			Expect(images[0].Width).To(Equal(640))
-			Expect(images[1].Width).To(Equal(320))
-			Expect(images[2].Width).To(Equal(160))
-		})
-
-		It("fails if artist was not found", func() {
-			httpClient.mock("https://api.spotify.com/v1/search", http.Response{
-				StatusCode: 200,
-				Body: io.NopCloser(bytes.NewBufferString(`{
-						  "artists" : {
-							"href" : "https://api.spotify.com/v1/search?query=dasdasdas%2Cdna&type=artist&offset=0&limit=20",
-							"items" : [ ], "limit" : 20, "next" : null, "offset" : 0, "previous" : null, "total" : 0
-						  }}`)),
-			})
-			httpClient.mock("https://accounts.spotify.com/api/token", http.Response{
-				StatusCode: 200,
-				Body:       io.NopCloser(bytes.NewBufferString(`{"access_token": "NEW_ACCESS_TOKEN","token_type": "Bearer","expires_in": 3600}`)),
-			})
-
-			_, err := client.searchArtists(context.TODO(), "U2", 10)
-			Expect(err).To(MatchError(ErrNotFound))
-		})
-
-		It("fails if not able to authorize", func() {
-			f, _ := os.Open("tests/fixtures/spotify.search.artist.json")
-			httpClient.mock("https://api.spotify.com/v1/search", http.Response{Body: f, StatusCode: 200})
-			httpClient.mock("https://accounts.spotify.com/api/token", http.Response{
-				StatusCode: 400,
-				Body:       io.NopCloser(bytes.NewBufferString(`{"error":"invalid_client","error_description":"Invalid client"}`)),
-			})
-
-			_, err := client.searchArtists(context.TODO(), "U2", 10)
-			Expect(err).To(MatchError("spotify error(invalid_client): Invalid client"))
-		})
-	})
-
-	Describe("authorize", func() {
-		It("returns an access_token on successful authorization", func() {
-			httpClient.mock("https://accounts.spotify.com/api/token", http.Response{
-				StatusCode: 200,
-				Body:       io.NopCloser(bytes.NewBufferString(`{"access_token": "NEW_ACCESS_TOKEN","token_type": "Bearer","expires_in": 3600}`)),
-			})
-
-			token, err := client.authorize(context.TODO())
-			Expect(err).To(BeNil())
-			Expect(token).To(Equal("NEW_ACCESS_TOKEN"))
-			auth := httpClient.lastRequest.Header.Get("Authorization")
-			Expect(auth).To(Equal("Basic U1BPVElGWV9JRDpTUE9USUZZX1NFQ1JFVA=="))
-		})
-
-		It("fails on unsuccessful authorization", func() {
-			httpClient.mock("https://accounts.spotify.com/api/token", http.Response{
-				StatusCode: 400,
-				Body:       io.NopCloser(bytes.NewBufferString(`{"error":"invalid_client","error_description":"Invalid client"}`)),
-			})
-
-			_, err := client.authorize(context.TODO())
-			Expect(err).To(MatchError("spotify error(invalid_client): Invalid client"))
-		})
-
-		It("fails on invalid JSON response", func() {
-			httpClient.mock("https://accounts.spotify.com/api/token", http.Response{
-				StatusCode: 200,
-				Body:       io.NopCloser(bytes.NewBufferString(`{NOT_VALID}`)),
-			})
-
-			_, err := client.authorize(context.TODO())
-			Expect(err).To(MatchError("invalid character 'N' looking for beginning of object key string"))
-		})
-	})
-})
-
-type fakeHttpClient struct {
-	responses   map[string]*http.Response
-	lastRequest *http.Request
-}
-
-func (c *fakeHttpClient) mock(url string, response http.Response) {
-	if c.responses == nil {
-		c.responses = make(map[string]*http.Response)
-	}
-	c.responses[url] = &response
-}
-
-func (c *fakeHttpClient) Do(req *http.Request) (*http.Response, error) {
-	c.lastRequest = req
-	u := req.URL
-	u.RawQuery = ""
-	if resp, ok := c.responses[u.String()]; ok {
-		return resp, nil
-	}
-	panic("URL not mocked: " + u.String())
-}
@@ -1,30 +0,0 @@
-package spotify
-
-type SearchResults struct {
-	Artists ArtistsResult `json:"artists"`
-}
-
-type ArtistsResult struct {
-	HRef  string   `json:"href"`
-	Items []Artist `json:"items"`
-}
-
-type Artist struct {
-	Genres     []string `json:"genres"`
-	HRef       string   `json:"href"`
-	ID         string   `json:"id"`
-	Popularity int      `json:"popularity"`
-	Images     []Image  `json:"images"`
-	Name       string   `json:"name"`
-}
-
-type Image struct {
-	URL    string `json:"url"`
-	Width  int    `json:"width"`
-	Height int    `json:"height"`
-}
-
-type Error struct {
-	Code    string `json:"error"`
-	Message string `json:"error_description"`
-}
@@ -1,48 +0,0 @@
-package spotify
-
-import (
-	"encoding/json"
-	"os"
-
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Responses", func() {
-	Describe("Search type=artist", func() {
-		It("parses the artist search result correctly ", func() {
-			var resp SearchResults
-			body, _ := os.ReadFile("tests/fixtures/spotify.search.artist.json")
-			err := json.Unmarshal(body, &resp)
-			Expect(err).To(BeNil())
-
-			Expect(resp.Artists.Items).To(HaveLen(20))
-			u2 := resp.Artists.Items[0]
-			Expect(u2.Name).To(Equal("U2"))
-			Expect(u2.Genres).To(ContainElements("irish rock", "permanent wave", "rock"))
-			Expect(u2.ID).To(Equal("51Blml2LZPmy7TTiAg47vQ"))
-			Expect(u2.HRef).To(Equal("https://api.spotify.com/v1/artists/51Blml2LZPmy7TTiAg47vQ"))
-			Expect(u2.Images[0].URL).To(Equal("https://i.scdn.co/image/e22d5c0c8139b8439440a69854ed66efae91112d"))
-			Expect(u2.Images[0].Width).To(Equal(640))
-			Expect(u2.Images[0].Height).To(Equal(640))
-			Expect(u2.Images[1].URL).To(Equal("https://i.scdn.co/image/40d6c5c14355cfc127b70da221233315497ec91d"))
-			Expect(u2.Images[1].Width).To(Equal(320))
-			Expect(u2.Images[1].Height).To(Equal(320))
-			Expect(u2.Images[2].URL).To(Equal("https://i.scdn.co/image/7293d6752ae8a64e34adee5086858e408185b534"))
-			Expect(u2.Images[2].Width).To(Equal(160))
-			Expect(u2.Images[2].Height).To(Equal(160))
-		})
-	})
-
-	Describe("Error", func() {
-		It("parses the error response correctly", func() {
-			var errorResp Error
-			body := []byte(`{"error":"invalid_client","error_description":"Invalid client"}`)
-			err := json.Unmarshal(body, &errorResp)
-			Expect(err).To(BeNil())
-
-			Expect(errorResp.Code).To(Equal("invalid_client"))
-			Expect(errorResp.Message).To(Equal("Invalid client"))
-		})
-	})
-})
@@ -1,96 +0,0 @@
-package spotify
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net/http"
-	"sort"
-	"strings"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core/agents"
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/utils/cache"
-	"github.com/xrash/smetrics"
-)
-
-const spotifyAgentName = "spotify"
-
-type spotifyAgent struct {
-	ds     model.DataStore
-	id     string
-	secret string
-	client *client
-}
-
-func spotifyConstructor(ds model.DataStore) agents.Interface {
-	if conf.Server.Spotify.ID == "" || conf.Server.Spotify.Secret == "" {
-		return nil
-	}
-	l := &spotifyAgent{
-		ds:     ds,
-		id:     conf.Server.Spotify.ID,
-		secret: conf.Server.Spotify.Secret,
-	}
-	hc := &http.Client{
-		Timeout: consts.DefaultHttpClientTimeOut,
-	}
-	chc := cache.NewHTTPClient(hc, consts.DefaultHttpClientTimeOut)
-	l.client = newClient(l.id, l.secret, chc)
-	return l
-}
-
-func (s *spotifyAgent) AgentName() string {
-	return spotifyAgentName
-}
-
-func (s *spotifyAgent) GetArtistImages(ctx context.Context, id, name, mbid string) ([]agents.ExternalImage, error) {
-	a, err := s.searchArtist(ctx, name)
-	if err != nil {
-		if errors.Is(err, model.ErrNotFound) {
-			log.Warn(ctx, "Artist not found in Spotify", "artist", name)
-		} else {
-			log.Error(ctx, "Error calling Spotify", "artist", name, err)
-		}
-		return nil, err
-	}
-
-	var res []agents.ExternalImage
-	for _, img := range a.Images {
-		res = append(res, agents.ExternalImage{
-			URL:  img.URL,
-			Size: img.Width,
-		})
-	}
-	return res, nil
-}
-
-func (s *spotifyAgent) searchArtist(ctx context.Context, name string) (*Artist, error) {
-	artists, err := s.client.searchArtists(ctx, name, 40)
-	if err != nil || len(artists) == 0 {
-		return nil, model.ErrNotFound
-	}
-	name = strings.ToLower(name)
-
-	// Sort results, prioritizing artists with images, with similar names and with high popularity, in this order
-	sort.Slice(artists, func(i, j int) bool {
-		ai := fmt.Sprintf("%-5t-%03d-%04d", len(artists[i].Images) == 0, smetrics.WagnerFischer(name, strings.ToLower(artists[i].Name), 1, 1, 2), 1000-artists[i].Popularity)
-		aj := fmt.Sprintf("%-5t-%03d-%04d", len(artists[j].Images) == 0, smetrics.WagnerFischer(name, strings.ToLower(artists[j].Name), 1, 1, 2), 1000-artists[j].Popularity)
-		return ai < aj
-	})
-
-	// If the first one has the same name, that's the one
-	if strings.ToLower(artists[0].Name) != name {
-		return nil, model.ErrNotFound
-	}
-	return &artists[0], err
-}
-
-func init() {
-	conf.AddHook(func() {
-		agents.Register(spotifyAgentName, spotifyConstructor)
-	})
-}
@@ -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))
-				}
-			}
-		})
-	})
-})
@@ -1,9 +0,0 @@
-//go:build !windows
-
-package taglib
-
-import "C"
-
-func getFilename(s string) *C.char {
-	return C.CString(s)
-}
@@ -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)
-}
@@ -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())
-	})
-}
@@ -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())
-			})
-		})
-	})
-
-})
@@ -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;
-}
@@ -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}
-	}
-}
@@ -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
@@ -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
+}
@@ -27,8 +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/spotify"
-	_ "github.com/navidrome/navidrome/adapters/taglib"
 )

 var (
@@ -196,7 +194,8 @@ func runInitialScan(ctx context.Context) func() error {
 		if err != nil {
 			return err
 		}
-		scanNeeded := conf.Server.Scanner.ScanOnStartup || inProgress || fullScanRequired == "1" || pidHasChanged
+		scanOnStartup := conf.Server.Scanner.Enabled && conf.Server.Scanner.ScanOnStartup
+		scanNeeded := scanOnStartup || inProgress || fullScanRequired == "1" || pidHasChanged
 		time.Sleep(2 * time.Second) // Wait 2 seconds before the initial scan
 		if scanNeeded {
 			s := CreateScanner(ctx)
@@ -9,6 +9,7 @@ import (
 	"strings"

 	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -74,7 +75,7 @@ func runScanner(ctx context.Context) {
 	sqlDB := db.Db()
 	defer db.Db().Close()
 	ds := persistence.New(sqlDB)
-	pls := core.NewPlaylists(ds)
+	pls := playlists.NewPlaylists(ds, core.NewImageUploadService())

 	// Parse targets from command line or file
 	var scanTargets []model.ScanTarget
@@ -248,6 +248,7 @@ ExecStart={{.Path|cmdEscape}}{{range .Arguments}} {{.|cmd}}{{end}}
 TimeoutStopSec=20
 RestartSec=120
 EnvironmentFile=-/etc/sysconfig/{{.Name}}
+Environment="ND_SYSTEMD_PRIORITY_LOGGING=1"

 DevicePolicy=closed
 NoNewPrivileges=yes
@@ -1,6 +1,6 @@
 // Code generated by Wire. DO NOT EDIT.

-//go:generate go run -mod=mod github.com/google/wire/cmd/wire gen -tags "netgo"
+//go:generate go run -mod=mod github.com/google/wire/cmd/wire gen -tags "netgo sqlite_fts5"
 //go:build !wireinject
 // +build !wireinject

@@ -16,9 +16,14 @@ import (
 	"github.com/navidrome/navidrome/core/artwork"
 	"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"
 	"github.com/navidrome/navidrome/persistence"
@@ -36,8 +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/spotify"
-	_ "github.com/navidrome/navidrome/adapters/taglib"
 )

 // Injectors from wire_injectors.go:
@@ -61,7 +64,8 @@ func CreateNativeAPIRouter(ctx context.Context) *nativeapi.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
 	share := core.NewShare(dataStore)
-	playlists := core.NewPlaylists(dataStore)
+	imageUploadService := core.NewImageUploadService()
+	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
 	insights := metrics.GetInstance(dataStore)
 	fileCache := artwork.GetImageCache()
 	fFmpeg := ffmpeg.New()
@@ -69,15 +73,16 @@ 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, playlists, metricsMetrics)
+	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
 	watcher := scanner.GetWatcher(dataStore, modelScanner)
 	library := core.NewLibrary(dataStore, modelScanner, watcher, broker, manager)
 	user := core.NewUser(dataStore, manager)
 	maintenance := core.NewMaintenance(dataStore)
-	router := nativeapi.New(dataStore, share, playlists, insights, library, user, maintenance, manager)
+	router := nativeapi.New(dataStore, share, playlistsPlaylists, insights, library, user, maintenance, manager, imageUploadService)
 	return router
 }

@@ -90,19 +95,24 @@ 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 := core.GetTranscodingCache()
-	mediaStreamer := core.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
+	transcodingCache := stream.GetTranscodingCache()
+	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
 	share := core.NewShare(dataStore)
 	archiver := core.NewArchiver(mediaStreamer, dataStore, share)
 	players := core.NewPlayers(dataStore)
 	cacheWarmer := artwork.NewCacheWarmer(artworkArtwork, fileCache)
-	playlists := core.NewPlaylists(dataStore)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlists, metricsMetrics)
+	imageUploadService := core.NewImageUploadService()
+	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
+	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
 	playTracker := scrobbler.GetPlayTracker(dataStore, broker, manager)
 	playbackServer := playback.GetInstance(dataStore)
-	router := subsonic.New(dataStore, artworkArtwork, mediaStreamer, archiver, players, provider, modelScanner, broker, playlists, playTracker, share, playbackServer, metricsMetrics)
+	lyricsLyrics := lyrics.NewLyrics(manager)
+	transcodeDecider := stream.NewTranscodeDecider(dataStore, fFmpeg)
+	sonicSonic := sonic.New(dataStore, manager, matcherMatcher)
+	router := subsonic.New(dataStore, artworkArtwork, mediaStreamer, archiver, players, provider, modelScanner, broker, playlistsPlaylists, playTracker, share, playbackServer, metricsMetrics, lyricsLyrics, transcodeDecider, sonicSonic)
 	return router
 }

@@ -115,10 +125,11 @@ 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 := core.GetTranscodingCache()
-	mediaStreamer := core.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
+	transcodingCache := stream.GetTranscodingCache()
+	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
 	share := core.NewShare(dataStore)
 	archiver := core.NewArchiver(mediaStreamer, dataStore, share)
 	router := public.New(dataStore, artworkArtwork, mediaStreamer, share, archiver)
@@ -162,11 +173,13 @@ 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)
-	playlists := core.NewPlaylists(dataStore)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlists, metricsMetrics)
+	imageUploadService := core.NewImageUploadService()
+	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
+	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
 	return modelScanner
 }

@@ -179,11 +192,13 @@ 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)
-	playlists := core.NewPlaylists(dataStore)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlists, metricsMetrics)
+	imageUploadService := core.NewImageUploadService()
+	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
+	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
 	watcher := scanner.GetWatcher(dataStore, modelScanner)
 	return watcher
 }
@@ -206,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(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()
@@ -11,9 +11,11 @@ import (
 	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/core/lyrics"
 	"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"
@@ -42,8 +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)),
@@ -1,4 +0,0 @@
-package buildtags
-
-// This file is left intentionally empty. It is used to make sure the package is not empty, in the case all
-// required build tags are disabled.
@@ -0,0 +1,6 @@
+// Package buildtags provides compile-time enforcement of required build tags.
+//
+// Each file in this package is guarded by a build constraint and exports a variable
+// that main.go references. If a required tag is missing during compilation, the build
+// fails with an "undefined" error, directing the developer to use `make build`.
+package buildtags
@@ -2,10 +2,6 @@

 package buildtags

-// NOTICE: This file was created to force the inclusion of the `netgo` tag when compiling the project.
-// If the tag is not included, the compilation will fail because this variable won't be defined, and the `main.go`
-// file requires it.
-
-// Why this tag is required? See https://github.com/navidrome/navidrome/issues/700
+// The `netgo` tag is required when compiling the project. See https://github.com/navidrome/navidrome/issues/700

 var NETGO = true
@@ -0,0 +1,8 @@
+//go:build sqlite_fts5
+
+package buildtags
+
+// FTS5 is required for full-text search. Without this tag, the SQLite driver
+// won't include FTS5 support, causing runtime failures on migrations and search queries.
+
+var SQLITE_FTS5 = true
@@ -12,12 +12,13 @@ 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"
 	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/scheduler"
 	"github.com/navidrome/navidrome/utils/run"
-	"github.com/robfig/cron/v3"
 	"github.com/spf13/viper"
 )

@@ -26,6 +27,7 @@ type configOptions struct {
 	Address                         string
 	Port                            int
 	UnixSocketPerm                  string
+	EnforceNonRootUser              bool
 	MusicFolder                     string
 	DataFolder                      string
 	CacheFolder                     string
@@ -46,6 +48,7 @@ type configOptions struct {
 	EnableTranscodingCancellation   bool
 	EnableDownloads                 bool
 	EnableExternalServices          bool
+	EnableM3UExternalAlbumArt       bool
 	EnableInsightsCollector         bool
 	EnableMediaFileCoverArt         bool
 	TranscodingCacheSize            string
@@ -58,8 +61,8 @@ type configOptions struct {
 	SmartPlaylistRefreshDelay       time.Duration
 	AutoTranscodeDownload           bool
 	DefaultDownsamplingFormat       string
-	SearchFullString                bool
-	SimilarSongsMatchThreshold      int
+	Search                          searchOptions  `json:",omitzero"`
+	Matcher                         matcherOptions `json:",omitzero"`
 	RecentlyAddedByModTime          bool
 	PreferSortTags                  bool
 	IgnoredArticles                 string
@@ -68,13 +71,18 @@ type configOptions struct {
 	MPVPath                         string
 	MPVCmdTemplate                  string
 	CoverArtPriority                string
-	CoverJpegQuality                int
+	CoverArtQuality                 int
+	EnableWebPEncoding              bool
 	ArtistArtPriority               string
+	ArtistImageFolder               string
+	DiscArtPriority                 string
 	LyricsPriority                  string
 	EnableGravatar                  bool
 	EnableFavourites                bool
 	EnableStarRating                bool
 	EnableUserEditing               bool
+	EnableArtworkUpload             bool
+	MaxImageUploadSize              string
 	EnableSharing                   bool
 	ShareURL                        string
 	DefaultShareExpiration          time.Duration
@@ -82,9 +90,12 @@ type configOptions struct {
 	DefaultTheme                    string
 	DefaultLanguage                 string
 	DefaultUIVolume                 int
+	UISearchDebounceMs              int
+	UICoverArtSize                  int
 	EnableReplayGain                bool
 	EnableCoverAnimation            bool
 	EnableNowPlaying                bool
+	UIPlaybackReportInterval        time.Duration
 	GATrackingID                    string
 	EnableLogRedacting              bool
 	AuthRequestLimit                int
@@ -101,7 +112,6 @@ type configOptions struct {
 	Inspect                         inspectOptions      `json:",omitzero"`
 	Subsonic                        subsonicOptions     `json:",omitzero"`
 	LastFM                          lastfmOptions       `json:",omitzero"`
-	Spotify                         spotifyOptions      `json:",omitzero"`
 	Deezer                          deezerOptions       `json:",omitzero"`
 	ListenBrainz                    listenBrainzOptions `json:",omitzero"`
 	EnableScrobbleHistory           bool
@@ -129,7 +139,6 @@ type configOptions struct {
 	DevExternalScanner                bool
 	DevScannerThreads                 uint
 	DevSelectiveWatcher               bool
-	DevLegacyEmbedImage               bool
 	DevInsightsInitialDelay           time.Duration
 	DevEnablePlayerInsights           bool
 	DevEnablePluginsInsights          bool
@@ -137,6 +146,7 @@ type configOptions struct {
 	DevExternalArtistFetchMultiplier  float64
 	DevOptimizeDB                     bool
 	DevPreserveUnicodeInExternalCalls bool
+	DevEnableMediaFileProbe           bool
 }

 type scannerOptions struct {
@@ -154,6 +164,7 @@ type scannerOptions struct {

 type subsonicOptions struct {
 	AppendSubtitle        bool
+	AppendAlbumVersion    bool
 	ArtistParticipations  bool
 	DefaultReportRealPath bool
 	EnableAverageRating   bool
@@ -172,8 +183,8 @@ type TagConf struct {

 type lastfmOptions struct {
 	Enabled                 bool
-	ApiKey                  string
-	Secret                  string
+	ApiKey                  string //nolint:gosec
+	Secret                  string //nolint:gosec
 	Language                string
 	ScrobbleFirstArtistOnly bool

@@ -181,11 +192,6 @@ type lastfmOptions struct {
 	Languages []string // Computed from Language, split by comma
 }

-type spotifyOptions struct {
-	ID     string
-	Secret string
-}
-
 type deezerOptions struct {
 	Enabled  bool
 	Language string
@@ -208,7 +214,7 @@ type httpHeaderOptions struct {
 type prometheusOptions struct {
 	Enabled     bool
 	MetricsPath string
-	Password    string
+	Password    string //nolint:gosec
 }

 type AudioDeviceDefinition []string
@@ -249,6 +255,30 @@ type pluginsOptions struct {
 type extAuthOptions struct {
 	TrustedSources string
 	UserHeader     string
+	LogoutURL      string
+}
+
+type searchOptions struct {
+	Backend    string
+	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) {
+	_, _ = fmt.Fprintln(os.Stderr, append([]any{"FATAL:"}, args...)...)
+	os.Exit(1)
+}
+
+var getEUID = os.Geteuid
+
+var currentGOOS = func() string {
+	return runtime.GOOS
 }

 var (
@@ -260,30 +290,35 @@ func LoadFromFile(confFile string) {
 	viper.SetConfigFile(confFile)
 	err := viper.ReadInConfig()
 	if err != nil {
-		_, _ = fmt.Fprintln(os.Stderr, "FATAL: Error reading config file:", err)
-		os.Exit(1)
+		logFatal("Error reading config file:", err)
 	}
 	Load(true)
 }

 func Load(noConfigDump bool) {
 	parseIniFileConfiguration()
+	remapEnvVarKeysFromConfig()

 	// Map deprecated options to their new names for backwards compatibility
 	mapDeprecatedOption("ReverseProxyWhitelist", "ExtAuth.TrustedSources")
 	mapDeprecatedOption("ReverseProxyUserHeader", "ExtAuth.UserHeader")
 	mapDeprecatedOption("HTTPSecurityHeaders.CustomFrameOptionsValue", "HTTPHeaders.FrameOptions")
+	mapDeprecatedOption("CoverJpegQuality", "CoverArtQuality")
+	mapDeprecatedOption("SimilarSongsMatchThreshold", "Matcher.FuzzyThreshold")

 	err := viper.Unmarshal(&Server)
 	if err != nil {
-		_, _ = fmt.Fprintln(os.Stderr, "FATAL: Error parsing config:", err)
-		os.Exit(1)
+		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 {
-		_, _ = fmt.Fprintln(os.Stderr, "FATAL: Error creating data path:", err)
-		os.Exit(1)
+		logFatal("Error creating data path:", err)
 	}

 	if Server.CacheFolder == "" {
@@ -291,8 +326,12 @@ func Load(noConfigDump bool) {
 	}
 	err = os.MkdirAll(Server.CacheFolder, os.ModePerm)
 	if err != nil {
-		_, _ = fmt.Fprintln(os.Stderr, "FATAL: Error creating cache path:", err)
-		os.Exit(1)
+		logFatal("Error creating cache path:", err)
+	}
+
+	err = os.MkdirAll(filepath.Join(Server.DataFolder, consts.ArtworkFolder), os.ModePerm)
+	if err != nil {
+		logFatal("Error creating artwork path:", err)
 	}

 	if Server.Plugins.Enabled {
@@ -301,8 +340,7 @@ func Load(noConfigDump bool) {
 		}
 		err = os.MkdirAll(Server.Plugins.Folder, 0700)
 		if err != nil {
-			_, _ = fmt.Fprintln(os.Stderr, "FATAL: Error creating plugins path:", err)
-			os.Exit(1)
+			logFatal("Error creating plugins path:", err)
 		}
 	}

@@ -314,8 +352,7 @@ func Load(noConfigDump bool) {
 	if Server.Backup.Path != "" {
 		err = os.MkdirAll(Server.Backup.Path, os.ModePerm)
 		if err != nil {
-			_, _ = fmt.Fprintln(os.Stderr, "FATAL: Error creating backup path:", err)
-			os.Exit(1)
+			logFatal("Error creating backup path:", err)
 		}
 	}

@@ -323,10 +360,15 @@ func Load(noConfigDump bool) {
 	if Server.LogFile != "" {
 		out, err = os.OpenFile(Server.LogFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
 		if err != nil {
-			_, _ = fmt.Fprintf(os.Stderr, "FATAL: Error opening log file %s: %s\n", Server.LogFile, err.Error())
-			os.Exit(1)
+			logFatal(fmt.Sprintf("Error opening log file %s: %s", Server.LogFile, err.Error()))
 		}
 		log.SetOutput(out)
+	} else if os.Getenv("ND_SYSTEMD_PRIORITY_LOGGING") != "" && os.Getenv("JOURNAL_STREAM") != "" {
+		// When running under systemd, prepend syslog priority prefixes so
+		// journald assigns the correct severity to each log line.
+		// Note that we have an additional environment variable, as JOURNAL_STREAM
+		// can be present in a systemd environment even if not running as a systemd service
+		log.EnableJournalFormat()
 	}

 	log.SetLevelString(Server.LogLevel)
@@ -339,16 +381,19 @@ 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)
+
 	if Server.BaseURL != "" {
 		u, err := url.Parse(Server.BaseURL)
 		if err != nil {
-			_, _ = fmt.Fprintln(os.Stderr, "FATAL: Invalid BaseURL:", err)
-			os.Exit(1)
+			logFatal("Invalid BaseURL:", err)
 		}
 		Server.BasePath = u.Path
 		u.Path = ""
@@ -389,12 +434,26 @@ func Load(noConfigDump bool) {
 	// Parse Deezer.Language into Languages slice (comma-separated, with fallback to DefaultInfoLanguage)
 	Server.Deezer.Languages = parseLanguages(Server.Deezer.Language)

+	// Deprecated options
 	logDeprecatedOptions("Scanner.GenreSeparators", "")
 	logDeprecatedOptions("Scanner.GroupAlbumReleases", "")
 	logDeprecatedOptions("DevEnableBufferedScrobble", "") // Deprecated: Buffered scrobbling is now always enabled and this option is ignored
+	logDeprecatedOptions("SearchFullString", "Search.FullString")
 	logDeprecatedOptions("ReverseProxyWhitelist", "ExtAuth.TrustedSources")
 	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 {
@@ -420,6 +479,52 @@ func logDeprecatedOptions(oldName, newName string) {
 	}
 }

+// logRemovedOptions checks if the option is set, and if yes, outputs a warning message saying the option is
+// not available anymore
+func logRemovedOptions(options ...string) {
+	for _, option := range options {
+		envVar := "ND_" + strings.ToUpper(strings.ReplaceAll(option, ".", "_"))
+		logWarning := func(option string) {
+			log.Warn(fmt.Sprintf("Option '%s' is not available anymore and will be ignored. Please remove it from your config", option))
+		}
+		if viper.InConfig(option) {
+			logWarning(option)
+		}
+		if os.Getenv(envVar) != "" {
+			logWarning(envVar)
+		}
+	}
+}
+
+// remapEnvVarKeysFromConfig detects ND_-prefixed keys in the config file (users mistakenly
+// using environment variable names) and remaps them to canonical Viper keys with a warning.
+func remapEnvVarKeysFromConfig() {
+	for _, key := range viper.AllKeys() {
+		if !strings.HasPrefix(key, "nd_") || !viper.InConfig(key) {
+			continue
+		}
+		stripped := strings.TrimPrefix(key, "nd_")
+		canonicalKey := strings.ReplaceAll(stripped, "_", ".")
+		displayNDKey := "ND_" + strings.ToUpper(stripped)
+		displayCanonical := toPascalCase(canonicalKey)
+
+		if viper.InConfig(canonicalKey) {
+			logFatal(fmt.Sprintf(
+				"Config file contains both '%s' and '%s'. Remove the ND_-prefixed version. "+
+					"The 'ND_' prefix is only needed for environment variables, not config file keys.",
+				displayNDKey, displayCanonical,
+			))
+			return
+		}
+
+		viper.Set(canonicalKey, viper.Get(key))
+		_, _ = fmt.Fprintf(os.Stderr, "WARNING: Config key '%s' uses environment variable naming. Use '%s' instead. "+
+			"The 'ND_' prefix is only needed for environment variables.\n",
+			displayNDKey, displayCanonical,
+		)
+	}
+}
+
 // mapDeprecatedOption is used to provide backwards compatibility for deprecated options. It should be called after
 // the config has been read by viper, but before unmarshalling it into the Config struct.
 func mapDeprecatedOption(legacyName, newName string) {
@@ -437,18 +542,15 @@ func parseIniFileConfiguration() {
 		var iniConfig map[string]any
 		err := viper.Unmarshal(&iniConfig)
 		if err != nil {
-			_, _ = fmt.Fprintln(os.Stderr, "FATAL: Error parsing config:", err)
-			os.Exit(1)
+			logFatal("Error parsing config:", err)
 		}
 		cfg, ok := iniConfig["default"].(map[string]any)
 		if !ok {
-			_, _ = fmt.Fprintln(os.Stderr, "FATAL: Error parsing config: missing [default] section:", iniConfig)
-			os.Exit(1)
+			logFatal("Error parsing config: missing [default] section:", iniConfig)
 		}
 		err = viper.MergeConfigMap(cfg)
 		if err != nil {
-			_, _ = fmt.Fprintln(os.Stderr, "FATAL: Error parsing config:", err)
-			os.Exit(1)
+			logFatal("Error parsing config:", err)
 		}
 	}
 }
@@ -456,8 +558,8 @@ func parseIniFileConfiguration() {
 func disableExternalServices() {
 	log.Info("All external integrations are DISABLED!")
 	Server.EnableInsightsCollector = false
+	Server.EnableM3UExternalAlbumArt = false
 	Server.LastFM.Enabled = false
-	Server.Spotify.ID = ""
 	Server.Deezer.Enabled = false
 	Server.ListenBrainz.Enabled = false
 	Server.Agents = ""
@@ -470,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
@@ -498,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 = ""
@@ -526,17 +645,58 @@ func validateBackupSchedule() error {
 }

 func validateSchedule(schedule, field string) (string, error) {
-	if _, err := time.ParseDuration(schedule); err == nil {
-		schedule = "@every " + schedule
-	}
-	c := cron.New()
-	id, err := c.AddFunc(schedule, func() {})
+	_, 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)
-	} else {
-		c.Remove(id)
+		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.
+// It returns a function that can be used as a hook to validate URLs in the config.
+func validateURL(optionName, optionURL string) func() error {
+	return func() error {
+		if optionURL == "" {
+			return nil
+		}
+		u, err := url.Parse(optionURL)
+		if err != nil {
+			return fmt.Errorf("invalid %s %q: %w", optionName, optionURL, err)
+		}
+		if u.Scheme != "http" && u.Scheme != "https" {
+			return fmt.Errorf("invalid scheme for %s: '%s'. Only 'http' and 'https' are allowed", optionName, u.Scheme)
+		}
+		if u.Host == "" || u.Opaque != "" {
+			return fmt.Errorf("invalid %s: '%s'. A full http(s) URL with a non-empty host is required", optionName, optionURL)
+		}
+		return nil
+	}
+}
+
+func normalizeSearchBackend(value string) string {
+	v := strings.ToLower(strings.TrimSpace(value))
+	switch v {
+	case "fts", "legacy":
+		return v
+	default:
+		log.Error("Invalid Search.Backend value, falling back to 'fts'", "value", value)
+		return "fts"
+	}
+}
+
+// toPascalCase converts a dotted lowercase config key to PascalCase for display.
+// Example: "scanner.schedule" → "Scanner.Schedule"
+func toPascalCase(key string) string {
+	if key == "" {
+		return ""
+	}
+	parts := strings.Split(key, ".")
+	for i, part := range parts {
+		if len(part) > 0 {
+			parts[i] = strings.ToUpper(part[:1]) + part[1:]
+		}
+	}
+	return strings.Join(parts, ".")
 }

 // AddHook is used to register initialization code that should run as soon as the config is loaded
@@ -563,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", "")
@@ -582,20 +743,27 @@ func setViperDefaults() {
 	viper.SetDefault("smartPlaylistRefreshDelay", 5*time.Second)
 	viper.SetDefault("enabledownloads", true)
 	viper.SetDefault("enableexternalservices", true)
+	viper.SetDefault("enablem3uexternalalbumart", false)
 	viper.SetDefault("enablemediafilecoverart", true)
 	viper.SetDefault("autotranscodedownload", false)
 	viper.SetDefault("defaultdownsamplingformat", consts.DefaultDownsamplingFormat)
-	viper.SetDefault("searchfullstring", false)
-	viper.SetDefault("similarsongsmatchthreshold", 85)
+	viper.SetDefault("search.fullstring", false)
+	viper.SetDefault("search.backend", "fts")
+	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")
 	viper.SetDefault("indexgroups", "A B C D E F G H I J K L M N O P Q R S T U V W X-Z(XYZ) [Unknown]([)")
 	viper.SetDefault("ffmpegpath", "")
+	viper.SetDefault("mpvpath", "")
 	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("coverjpegquality", 75)
+	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")
 	viper.SetDefault("lyricspriority", ".lrc,.txt,embedded")
 	viper.SetDefault("enablegravatar", false)
 	viper.SetDefault("enablefavourites", true)
@@ -604,9 +772,14 @@ func setViperDefaults() {
 	viper.SetDefault("defaulttheme", "Dark")
 	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)
@@ -619,6 +792,7 @@ func setViperDefaults() {
 	viper.SetDefault("passwordencryptionkey", "")
 	viper.SetDefault("extauth.userheader", "Remote-User")
 	viper.SetDefault("extauth.trustedsources", "")
+	viper.SetDefault("extauth.logouturl", "")
 	viper.SetDefault("prometheus.enabled", false)
 	viper.SetDefault("prometheus.metricspath", consts.PrometheusDefaultPath)
 	viper.SetDefault("prometheus.password", "")
@@ -637,19 +811,18 @@ func setViperDefaults() {
 	viper.SetDefault("scanner.followsymlinks", true)
 	viper.SetDefault("scanner.purgemissing", consts.PurgeMissingNever)
 	viper.SetDefault("subsonic.appendsubtitle", true)
+	viper.SetDefault("subsonic.appendalbumversion", true)
 	viper.SetDefault("subsonic.artistparticipations", false)
 	viper.SetDefault("subsonic.defaultreportrealpath", false)
 	viper.SetDefault("subsonic.enableaveragerating", true)
 	viper.SetDefault("subsonic.legacyclients", "DSub")
 	viper.SetDefault("subsonic.minimalclients", "SubMusic")
-	viper.SetDefault("agents", "lastfm,spotify,deezer")
+	viper.SetDefault("agents", "deezer,lastfm,listenbrainz")
 	viper.SetDefault("lastfm.enabled", true)
 	viper.SetDefault("lastfm.language", consts.DefaultInfoLanguage)
 	viper.SetDefault("lastfm.apikey", "")
 	viper.SetDefault("lastfm.secret", "")
 	viper.SetDefault("lastfm.scrobblefirstartistonly", false)
-	viper.SetDefault("spotify.id", "")
-	viper.SetDefault("spotify.secret", "")
 	viper.SetDefault("deezer.enabled", true)
 	viper.SetDefault("deezer.language", consts.DefaultInfoLanguage)
 	viper.SetDefault("listenbrainz.enabled", true)
@@ -671,6 +844,7 @@ func setViperDefaults() {
 	viper.SetDefault("plugins.enabled", true)
 	viper.SetDefault("plugins.cachesize", "200MB")
 	viper.SetDefault("plugins.autoreload", false)
+	viper.SetDefault("plugins.loglevel", "")

 	// DevFlags. These are used to enable/disable debugging and incomplete features
 	viper.SetDefault("devlogsourceline", false)
@@ -684,7 +858,7 @@ func setViperDefaults() {
 	viper.SetDefault("devuishowconfig", true)
 	viper.SetDefault("devneweventstream", true)
 	viper.SetDefault("devoffsetoptimize", 50000)
-	viper.SetDefault("devartworkmaxrequests", max(2, runtime.NumCPU()/3))
+	viper.SetDefault("devartworkmaxrequests", max(2, runtime.NumCPU()/2))
 	viper.SetDefault("devartworkthrottlebackloglimit", consts.RequestThrottleBacklogLimit)
 	viper.SetDefault("devartworkthrottlebacklogtimeout", consts.RequestThrottleBacklogTimeout)
 	viper.SetDefault("devartistinfotimetolive", consts.ArtistInfoTimeToLive)
@@ -699,6 +873,7 @@ func setViperDefaults() {
 	viper.SetDefault("devexternalartistfetchmultiplier", 1.5)
 	viper.SetDefault("devoptimizedb", true)
 	viper.SetDefault("devpreserveunicodeinexternalcalls", false)
+	viper.SetDefault("devenablemediafileprobe", true)
 }

 func init() {
@@ -735,8 +910,7 @@ func InitConfig(cfgFile string, loadEnvVars bool) {

 	err := viper.ReadInConfig()
 	if viper.ConfigFileUsed() != "" && err != nil {
-		_, _ = fmt.Fprintln(os.Stderr, "FATAL: Navidrome could not open config file: ", err)
-		os.Exit(1)
+		logFatal("Navidrome could not open config file:", err)
 	}
 }

@@ -748,7 +922,7 @@ func getConfigFile(cfgFile string) string {
 	}
 	cfgFile = os.Getenv("ND_CONFIGFILE")
 	if cfgFile != "" {
-		if _, err := os.Stat(cfgFile); err == nil {
+		if _, err := os.Stat(cfgFile); err == nil { //nolint:gosec
 			return cfgFile
 		}
 	}
@@ -2,6 +2,7 @@ package conf_test

 import (
 	"fmt"
+	"os"
 	"path/filepath"
 	"testing"

@@ -24,6 +25,11 @@ var _ = Describe("Configuration", func() {
 		viper.SetDefault("datafolder", GinkgoT().TempDir())
 		viper.SetDefault("loglevel", "error")
 		conf.ResetConf()
+
+		// Panic instead of exiting on fatal errors to allow testing error conditions
+		DeferCleanup(conf.SetLogFatal(func(args ...any) {
+			panic(fmt.Sprint(args...))
+		}))
 	})

 	Describe("ParseLanguages", func() {
@@ -52,6 +58,241 @@ var _ = Describe("Configuration", func() {
 		})
 	})

+	Describe("ValidateURL", func() {
+		It("accepts a valid http URL", func() {
+			fn := conf.ValidateURL("TestOption", "http://example.com/path")
+			Expect(fn()).To(Succeed())
+		})
+
+		It("accepts a valid https URL", func() {
+			fn := conf.ValidateURL("TestOption", "https://example.com/path")
+			Expect(fn()).To(Succeed())
+		})
+
+		It("rejects a URL with no scheme", func() {
+			fn := conf.ValidateURL("TestOption", "example.com/path")
+			Expect(fn()).To(MatchError(ContainSubstring("invalid scheme")))
+		})
+
+		It("rejects a URL with an unsupported scheme", func() {
+			fn := conf.ValidateURL("TestOption", "javascript://example.com/path")
+			Expect(fn()).To(MatchError(ContainSubstring("invalid scheme")))
+		})
+
+		It("accepts an empty URL (optional config)", func() {
+			fn := conf.ValidateURL("TestOption", "")
+			Expect(fn()).To(Succeed())
+		})
+
+		It("includes the option name in the error message", func() {
+			fn := conf.ValidateURL("MyOption", "ftp://example.com")
+			Expect(fn()).To(MatchError(ContainSubstring("MyOption")))
+		})
+
+		It("rejects a URL that cannot be parsed", func() {
+			fn := conf.ValidateURL("TestOption", "://invalid")
+			Expect(fn()).To(HaveOccurred())
+		})
+
+		It("rejects a URL without a host", func() {
+			fn := conf.ValidateURL("TestOption", "http:///path")
+			Expect(fn()).To(MatchError(ContainSubstring("non-empty host is required")))
+		})
+	})
+
+	DescribeTable("NormalizeSearchBackend",
+		func(input, expected string) {
+			Expect(conf.NormalizeSearchBackend(input)).To(Equal(expected))
+		},
+		Entry("accepts 'fts'", "fts", "fts"),
+		Entry("accepts 'legacy'", "legacy", "legacy"),
+		Entry("normalizes 'FTS' to lowercase", "FTS", "fts"),
+		Entry("normalizes 'Legacy' to lowercase", "Legacy", "legacy"),
+		Entry("trims whitespace", "  fts  ", "fts"),
+		Entry("falls back to 'fts' for 'fts5'", "fts5", "fts"),
+		Entry("falls back to 'fts' for unrecognized values", "invalid", "fts"),
+		Entry("falls back to 'fts' for empty string", "", "fts"),
+	)
+
+	DescribeTable("ToPascalCase",
+		func(input, expected string) {
+			Expect(conf.ToPascalCase(input)).To(Equal(expected))
+		},
+		Entry("simple key", "address", "Address"),
+		Entry("dotted key", "scanner.schedule", "Scanner.Schedule"),
+		Entry("already capitalized", "Address", "Address"),
+		Entry("multi-segment", "lastfm.enabled", "Lastfm.Enabled"),
+		Entry("empty string", "", ""),
+	)
+
+	Describe("remapEnvVarKeysFromConfig", func() {
+		BeforeEach(func() {
+			viper.Reset()
+			conf.SetViperDefaults()
+			viper.SetDefault("datafolder", GinkgoT().TempDir())
+			viper.SetDefault("loglevel", "error")
+			conf.ResetConf()
+		})
+
+		It("remaps ND_-prefixed keys to canonical keys", func() {
+			filename := filepath.Join("testdata", "cfg_nd_keys.toml")
+			conf.InitConfig(filename, false)
+			conf.Load(true)
+
+			Expect(conf.Server.Address).To(Equal("127.0.0.1"))
+			Expect(conf.Server.Port).To(Equal(4531))
+			Expect(conf.Server.Scanner.Schedule).To(Equal("@every 1h"))
+		})
+
+		It("exits with fatal error when both ND_ and canonical key exist", func() {
+			filename := filepath.Join("testdata", "cfg_nd_conflict.toml")
+			conf.InitConfig(filename, false)
+
+			Expect(func() { conf.Load(true) }).To(PanicWith(And(
+				ContainSubstring("ND_ADDRESS"),
+				ContainSubstring("Address"),
+				ContainSubstring("only needed for environment variables"),
+			)))
+		})
+
+		It("does nothing when no ND_ keys are present", func() {
+			filename := filepath.Join("testdata", "cfg.toml")
+			conf.InitConfig(filename, false)
+			conf.Load(true)
+
+			// Verify normal config loading still works
+			Expect(conf.Server.MusicFolder).To(Equal("/toml/music"))
+		})
+	})
+
+	Describe("logFatal", func() {
+		var invalidPath string
+		BeforeEach(func() {
+			viper.Reset()
+			conf.SetViperDefaults()
+			viper.SetDefault("loglevel", "error")
+			conf.ResetConf()
+
+			// Create a file so that any path under it is invalid on all OSes
+			f, err := os.CreateTemp(GinkgoT().TempDir(), "blocker")
+			Expect(err).ToNot(HaveOccurred())
+			f.Close()
+			invalidPath = filepath.Join(f.Name(), "subdir")
+		})
+
+		It("is called when LoadFromFile gets an invalid config file", func() {
+			Expect(func() {
+				conf.LoadFromFile(filepath.Join(invalidPath, "file.toml"))
+			}).To(PanicWith(ContainSubstring("Error reading config file")))
+		})
+
+		It("is called when DataFolder is not writable", func() {
+			viper.SetDefault("datafolder", invalidPath)
+			Expect(func() {
+				conf.Load(true)
+			}).To(PanicWith(ContainSubstring("Error creating data path")))
+		})
+
+		It("is called when CacheFolder is not writable", func() {
+			viper.SetDefault("datafolder", GinkgoT().TempDir())
+			viper.SetDefault("cachefolder", invalidPath)
+			Expect(func() {
+				conf.Load(true)
+			}).To(PanicWith(ContainSubstring("Error creating cache path")))
+		})
+
+		It("is called when LogFile path is not writable", func() {
+			viper.SetDefault("datafolder", GinkgoT().TempDir())
+			viper.SetDefault("logfile", filepath.Join(invalidPath, "log.txt"))
+			Expect(func() {
+				conf.Load(true)
+			}).To(PanicWith(ContainSubstring("Error opening log file")))
+		})
+
+		It("is called when BaseURL is invalid", func() {
+			viper.SetDefault("datafolder", GinkgoT().TempDir())
+			viper.SetDefault("baseurl", "://invalid")
+			Expect(func() {
+				conf.Load(true)
+			}).To(PanicWith(ContainSubstring("Invalid BaseURL")))
+		})
+
+	})
+
+	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)
@@ -7,3 +7,28 @@ func ResetConf() {
 var SetViperDefaults = setViperDefaults

 var ParseLanguages = parseLanguages
+
+var ValidateURL = validateURL
+
+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
+	return func() { logFatal = old }
+}
@@ -0,0 +1,2 @@
+ND_ADDRESS = "127.0.0.1"
+Address = "0.0.0.0"
@@ -0,0 +1,3 @@
+ND_ADDRESS = "127.0.0.1"
+ND_PORT = 4531
+ND_SCANNER_SCHEDULE = "@every 1h"
@@ -65,12 +65,14 @@ const (

 	I18nFolder     = "i18n"
 	ScanIgnoreFile = ".ndignore"
+	ArtworkFolder  = "artwork"

-	PlaceholderArtistArt = "artist-placeholder.webp"
-	PlaceholderAlbumArt  = "album-placeholder.webp"
-	PlaceholderAvatar    = "logo-192x192.png"
-	UICoverArtSize       = 300
-	DefaultUIVolume      = 100
+	PlaceholderArtistArt            = "artist-placeholder.webp"
+	PlaceholderAlbumArt             = "album-placeholder.webp"
+	PlaceholderAvatar               = "logo-192x192.png"
+	DefaultUIVolume                 = 100
+	DefaultUISearchDebounceMs       = 200
+	DefaultUIPlaybackReportInterval = time.Minute

 	DefaultHttpClientTimeOut = 10 * time.Second

@@ -83,6 +85,11 @@ const (
 	Zwsp                    = string('\u200b')
 )

+const (
+	DefaultUICoverArtSize     = 300
+	DefaultMaxImageUploadSize = "10MB"
+)
+
 // Prometheus options
 const (
 	PrometheusDefaultPath = "/metrics"
@@ -101,6 +108,13 @@ const (
 	DefaultCacheCleanUpInterval = 10 * time.Minute
 )

+// Entity types
+const (
+	EntityArtist   = "artist"
+	EntityPlaylist = "playlist"
+	EntityRadio    = "radio"
+)
+
 const (
 	AlbumPlayCountModeAbsolute   = "absolute"
 	AlbumPlayCountModeNormalized = "normalized"
@@ -153,6 +167,12 @@ var (
 			DefaultBitRate: 256,
 			Command:        "ffmpeg -i %s -ss %t -map 0:a:0 -b:a %bk -v 0 -c:a aac -f adts -",
 		},
+		{
+			Name:           "flac audio",
+			TargetFormat:   "flac",
+			DefaultBitRate: 0,
+			Command:        "ffmpeg -i %s -ss %t -map 0:a:0 -v 0 -c:a flac -f flac -",
+		},
 	}
 )

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/navidrome/navidrome",
+  "public_key": "pk_WqzhKScNKWQ84J4n0oG0J"
+}
@@ -7,6 +7,6 @@ A new agent must comply with these simple implementation rules:
 2) Implement one or more of the `*Retriever()` interfaces. That's where the agent's logic resides.
 3) Register itself  (in its `init()` function).

-For an agent to be used it needs to be listed in the `Agents` config option (default is `"lastfm,spotify"`). The order dictates the priority of the agents
+For an agent to be used it needs to be listed in the `Agents` config option (default is `"deezer,lastfm"`). The order dictates the priority of the agents

 For a simple Agent example, look at the [local_agent](local_agent.go) agent source code.
@@ -10,9 +10,11 @@ import (
 	"strings"

 	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core/stream"
 	"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 {
@@ -22,13 +24,13 @@ type Archiver interface {
 	ZipPlaylist(ctx context.Context, id string, format string, bitrate int, w io.Writer) error
 }

-func NewArchiver(ms MediaStreamer, ds model.DataStore, shares Share) Archiver {
+func NewArchiver(ms stream.MediaStreamer, ds model.DataStore, shares Share) Archiver {
 	return &archiver{ds: ds, ms: ms, shares: shares}
 }

 type archiver struct {
 	ds     model.DataStore
-	ms     MediaStreamer
+	ms     stream.MediaStreamer
 	shares Share
 }

@@ -86,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 {
@@ -125,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,
@@ -155,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 {
@@ -176,7 +174,7 @@ func (a *archiver) addFileToZip(ctx context.Context, z *zip.Writer, mf model.Med

 	var r io.ReadCloser
 	if format != "raw" && format != "" {
-		r, err = a.ms.DoStream(ctx, &mf, format, bitrate, 0)
+		r, err = a.ms.NewStream(ctx, &mf, stream.Request{Format: format, BitRate: bitrate})
 	} else {
 		r, err = os.Open(path)
 	}
@@ -9,6 +9,7 @@ import (

 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/stream"
 	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -44,7 +45,7 @@ var _ = Describe("Archiver", func() {
 			}}).Return(mfs, nil)

 			ds.On("MediaFile", mock.Anything).Return(mfRepo)
-			ms.On("DoStream", mock.Anything, mock.Anything, "mp3", 128, 0).Return(io.NopCloser(strings.NewReader("test")), nil).Times(3)
+			ms.On("NewStream", mock.Anything, mock.Anything, stream.Request{Format: "mp3", BitRate: 128}).Return(io.NopCloser(strings.NewReader("test")), nil).Times(3)

 			out := new(bytes.Buffer)
 			err := arch.ZipAlbum(context.Background(), "1", "mp3", 128, out)
@@ -73,7 +74,7 @@ var _ = Describe("Archiver", func() {
 			}}).Return(mfs, nil)

 			ds.On("MediaFile", mock.Anything).Return(mfRepo)
-			ms.On("DoStream", mock.Anything, mock.Anything, "mp3", 128, 0).Return(io.NopCloser(strings.NewReader("test")), nil).Times(2)
+			ms.On("NewStream", mock.Anything, mock.Anything, stream.Request{Format: "mp3", BitRate: 128}).Return(io.NopCloser(strings.NewReader("test")), nil).Times(2)

 			out := new(bytes.Buffer)
 			err := arch.ZipArtist(context.Background(), "1", "mp3", 128, out)
@@ -104,7 +105,7 @@ var _ = Describe("Archiver", func() {
 			}

 			sh.On("Load", mock.Anything, "1").Return(share, nil)
-			ms.On("DoStream", mock.Anything, mock.Anything, "mp3", 128, 0).Return(io.NopCloser(strings.NewReader("test")), nil).Times(2)
+			ms.On("NewStream", mock.Anything, mock.Anything, stream.Request{Format: "mp3", BitRate: 128}).Return(io.NopCloser(strings.NewReader("test")), nil).Times(2)

 			out := new(bytes.Buffer)
 			err := arch.ZipShare(context.Background(), "1", out)
@@ -136,7 +137,7 @@ var _ = Describe("Archiver", func() {
 			plRepo := &mockPlaylistRepository{}
 			plRepo.On("GetWithTracks", "1", true, false).Return(pls, nil)
 			ds.On("Playlist", mock.Anything).Return(plRepo)
-			ms.On("DoStream", mock.Anything, mock.Anything, "mp3", 128, 0).Return(io.NopCloser(strings.NewReader("test")), nil).Times(2)
+			ms.On("NewStream", mock.Anything, mock.Anything, stream.Request{Format: "mp3", BitRate: 128}).Return(io.NopCloser(strings.NewReader("test")), nil).Times(2)

 			out := new(bytes.Buffer)
 			err := arch.ZipPlaylist(context.Background(), "1", "mp3", 128, out)
@@ -214,15 +215,15 @@ func (m *mockPlaylistRepository) GetWithTracks(id string, refreshSmartPlaylists,

 type mockMediaStreamer struct {
 	mock.Mock
-	core.MediaStreamer
+	stream.MediaStreamer
 }

-func (m *mockMediaStreamer) DoStream(ctx context.Context, mf *model.MediaFile, reqFormat string, reqBitRate int, reqOffset int) (*core.Stream, error) {
-	args := m.Called(ctx, mf, reqFormat, reqBitRate, reqOffset)
+func (m *mockMediaStreamer) NewStream(ctx context.Context, mf *model.MediaFile, req stream.Request) (*stream.Stream, error) {
+	args := m.Called(ctx, mf, req)
 	if args.Error(1) != nil {
 		return nil, args.Error(1)
 	}
-	return &core.Stream{ReadCloser: args.Get(0).(io.ReadCloser)}, nil
+	return &stream.Stream{ReadCloser: args.Get(0).(io.ReadCloser)}, nil
 }

 type mockShare struct {
@@ -0,0 +1,120 @@
+package artwork
+
+import (
+	"bytes"
+	"encoding/binary"
+)
+
+// isAnimatedGIF checks for multiple image descriptor blocks (0x2C) in a GIF file.
+// Animated GIFs use GIF89a and contain multiple image blocks.
+func isAnimatedGIF(data []byte) bool {
+	// GIF header: "GIF87a" or "GIF89a"
+	if !bytes.HasPrefix(data, []byte("GIF")) {
+		return false
+	}
+
+	// Skip header (6 bytes) + logical screen descriptor (7 bytes)
+	pos := 13
+	if pos >= len(data) {
+		return false
+	}
+
+	// Skip Global Color Table if present (bit 7 of packed byte at offset 10)
+	if len(data) > 10 && data[10]&0x80 != 0 {
+		// GCT size = 3 * 2^(N+1) where N = bits 0-2 of packed byte
+		gctSize := 3 * (1 << ((data[10] & 0x07) + 1))
+		pos += gctSize
+	}
+
+	frameCount := 0
+	for pos < len(data) {
+		switch data[pos] {
+		case 0x2C: // Image Descriptor - marks a frame
+			frameCount++
+			if frameCount > 1 {
+				return true
+			}
+			pos++ // skip introducer
+			if pos+8 >= len(data) {
+				return false
+			}
+			pos += 8 // skip x, y, w, h (each 2 bytes)
+			packed := data[pos]
+			pos++ // skip packed byte
+			// Skip Local Color Table if present
+			if packed&0x80 != 0 {
+				lctSize := 3 * (1 << ((packed & 0x07) + 1))
+				pos += lctSize
+			}
+			// Skip LZW minimum code size
+			pos++
+			// Skip sub-blocks
+			pos = skipGIFSubBlocks(data, pos)
+		case 0x21: // Extension block
+			pos++ // skip introducer
+			if pos >= len(data) {
+				return false
+			}
+			pos++ // skip extension label
+			// Skip sub-blocks
+			pos = skipGIFSubBlocks(data, pos)
+		case 0x3B: // Trailer
+			return false
+		default:
+			// Unknown block, bail
+			return false
+		}
+	}
+	return false
+}
+
+// skipGIFSubBlocks advances past a sequence of GIF sub-blocks (terminated by a zero-length block).
+func skipGIFSubBlocks(data []byte, pos int) int {
+	for pos < len(data) {
+		blockSize := int(data[pos])
+		pos++ // skip size byte
+		if blockSize == 0 {
+			break
+		}
+		pos += blockSize
+	}
+	return pos
+}
+
+// isAnimatedWebP checks for ANMF (animation frame) chunks in a WebP RIFF container.
+func isAnimatedWebP(data []byte) bool {
+	// WebP header: "RIFF" + 4 bytes size + "WEBP"
+	if !bytes.HasPrefix(data, []byte("RIFF")) || len(data) < 12 {
+		return false
+	}
+	if !bytes.Equal(data[8:12], []byte("WEBP")) {
+		return false
+	}
+	// Scan for ANMF chunk identifier
+	return bytes.Contains(data[12:], []byte("ANMF"))
+}
+
+// isAnimatedPNG checks for the acTL (animation control) chunk in a PNG file.
+// APNG files contain an acTL chunk that is not present in static PNGs.
+func isAnimatedPNG(data []byte) bool {
+	// PNG signature: 8 bytes
+	pngSig := []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A}
+	if !bytes.HasPrefix(data, pngSig) {
+		return false
+	}
+
+	// Scan chunks for "acTL" (animation control)
+	pos := uint64(8)
+	dataLen := uint64(len(data))
+	for pos+8 <= dataLen {
+		chunkLen := uint64(binary.BigEndian.Uint32(data[pos : pos+4]))
+		chunkType := string(data[pos+4 : pos+8])
+
+		if chunkType == "acTL" {
+			return true
+		}
+		// Move to next chunk: 4 (length) + 4 (type) + chunkLen (data) + 4 (CRC)
+		pos += 12 + chunkLen
+	}
+	return false
+}
@@ -0,0 +1,161 @@
+package artwork
+
+import (
+	"bytes"
+	"encoding/binary"
+	"image"
+	"image/color"
+	"image/gif"
+	"image/png"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Animation detection", func() {
+	Describe("isAnimatedGIF", func() {
+		It("detects an animated GIF with multiple frames", func() {
+			Expect(isAnimatedGIF(createAnimatedGIF(2))).To(BeTrue())
+		})
+
+		It("detects an animated GIF with many frames", func() {
+			Expect(isAnimatedGIF(createAnimatedGIF(5))).To(BeTrue())
+		})
+
+		It("does not flag a static GIF (single frame)", func() {
+			Expect(isAnimatedGIF(createAnimatedGIF(1))).To(BeFalse())
+		})
+
+		It("returns false for non-GIF data", func() {
+			Expect(isAnimatedGIF(nil)).To(BeFalse())
+			Expect(isAnimatedGIF([]byte{0xFF, 0xD8})).To(BeFalse())
+		})
+	})
+
+	Describe("isAnimatedWebP", func() {
+		It("detects an animated WebP with ANMF chunk", func() {
+			Expect(isAnimatedWebP(createAnimatedWebPBytes())).To(BeTrue())
+		})
+
+		It("does not flag a static WebP (no ANMF chunk)", func() {
+			Expect(isAnimatedWebP(createStaticWebPBytes())).To(BeFalse())
+		})
+
+		It("returns false for non-WebP data", func() {
+			Expect(isAnimatedWebP(nil)).To(BeFalse())
+			Expect(isAnimatedWebP([]byte{0xFF, 0xD8})).To(BeFalse())
+		})
+	})
+
+	Describe("isAnimatedPNG", func() {
+		It("detects an APNG with acTL chunk", func() {
+			Expect(isAnimatedPNG(createAPNGBytes())).To(BeTrue())
+		})
+
+		It("does not flag a static PNG (no acTL chunk)", func() {
+			Expect(isAnimatedPNG(createStaticPNGBytes())).To(BeFalse())
+		})
+
+		It("returns false for non-PNG data", func() {
+			Expect(isAnimatedPNG(nil)).To(BeFalse())
+			Expect(isAnimatedPNG([]byte{0xFF, 0xD8})).To(BeFalse())
+		})
+	})
+})
+
+// createAnimatedGIF creates a minimal animated GIF with the given number of frames.
+func createAnimatedGIF(frames int) []byte {
+	g := &gif.GIF{
+		LoopCount: 0,
+	}
+	for range frames {
+		img := image.NewPaletted(image.Rect(0, 0, 2, 2), color.Palette{color.Black, color.White})
+		g.Image = append(g.Image, img)
+		g.Delay = append(g.Delay, 10)
+	}
+	var buf bytes.Buffer
+	err := gif.EncodeAll(&buf, g)
+	if err != nil {
+		panic(err)
+	}
+	return buf.Bytes()
+}
+
+// writeUint32LE appends a little-endian uint32 to the buffer.
+func writeUint32LE(buf *bytes.Buffer, v uint32) {
+	b := make([]byte, 4)
+	binary.LittleEndian.PutUint32(b, v)
+	buf.Write(b)
+}
+
+// writeUint32BE appends a big-endian uint32 to the buffer.
+func writeUint32BE(buf *bytes.Buffer, v uint32) {
+	b := make([]byte, 4)
+	binary.BigEndian.PutUint32(b, v)
+	buf.Write(b)
+}
+
+// createAnimatedWebPBytes creates a minimal RIFF/WEBP container with an ANMF chunk.
+func createAnimatedWebPBytes() []byte {
+	var buf bytes.Buffer
+	buf.WriteString("RIFF")
+	writeUint32LE(&buf, 100) // file size placeholder
+	buf.WriteString("WEBP")
+	// VP8X chunk (extended format, required for animation)
+	buf.WriteString("VP8X")
+	writeUint32LE(&buf, 10)
+	buf.Write(make([]byte, 10))
+	// ANIM chunk (animation parameters)
+	buf.WriteString("ANIM")
+	writeUint32LE(&buf, 6)
+	buf.Write(make([]byte, 6))
+	// ANMF chunk (animation frame)
+	buf.WriteString("ANMF")
+	writeUint32LE(&buf, 16)
+	buf.Write(make([]byte, 16))
+	return buf.Bytes()
+}
+
+// createStaticWebPBytes creates a minimal RIFF/WEBP container without ANMF chunks.
+func createStaticWebPBytes() []byte {
+	var buf bytes.Buffer
+	buf.WriteString("RIFF")
+	writeUint32LE(&buf, 20) // file size
+	buf.WriteString("WEBP")
+	// VP8 chunk (simple lossy format)
+	buf.WriteString("VP8 ")
+	writeUint32LE(&buf, 4)
+	buf.Write(make([]byte, 4))
+	return buf.Bytes()
+}
+
+// createAPNGBytes creates a minimal PNG with an acTL chunk (making it APNG).
+func createAPNGBytes() []byte {
+	// Start with a real PNG
+	staticPNG := createStaticPNGBytes()
+
+	// Insert an acTL chunk after the IHDR chunk.
+	// PNG structure: signature (8) + IHDR chunk (4 len + 4 type + 13 data + 4 crc = 25)
+	ihdrEnd := 8 + 25
+	var buf bytes.Buffer
+	buf.Write(staticPNG[:ihdrEnd])
+	// Write acTL chunk: length=8, type="acTL", data=num_frames(4)+num_plays(4), CRC=4
+	writeUint32BE(&buf, 8) // chunk data length
+	buf.WriteString("acTL")
+	writeUint32BE(&buf, 2) // num_frames
+	writeUint32BE(&buf, 0) // num_plays (0 = infinite)
+	writeUint32BE(&buf, 0) // CRC placeholder
+	buf.Write(staticPNG[ihdrEnd:])
+	return buf.Bytes()
+}
+
+// createStaticPNGBytes creates a minimal valid static PNG.
+func createStaticPNGBytes() []byte {
+	img := image.NewRGBA(image.Rect(0, 0, 2, 2))
+	var buf bytes.Buffer
+	err := png.Encode(&buf, img)
+	if err != nil {
+		panic(err)
+	}
+	return buf.Bytes()
+}
@@ -122,6 +122,10 @@ func (a *artwork) getArtworkReader(ctx context.Context, artID model.ArtworkID, s
 			artReader, err = newMediafileArtworkReader(ctx, a, artID)
 		case model.KindPlaylistArtwork:
 			artReader, err = newPlaylistArtworkReader(ctx, a, artID)
+		case model.KindDiscArtwork:
+			artReader, err = newDiscArtworkReader(ctx, a, artID)
+		case model.KindRadioArtwork:
+			artReader, err = newRadioArtworkReader(ctx, a, artID)
 		default:
 			return nil, ErrUnavailable
 		}
@@ -9,7 +9,9 @@ import (
 	"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"
@@ -25,7 +27,7 @@ var _ = Describe("Artwork", func() {
 	var ffmpeg *tests.MockFFmpeg
 	var folderRepo *fakeFolderRepo
 	ctx := log.NewContext(context.TODO())
-	var alOnlyEmbed, alEmbedNotFound, alOnlyExternal, alExternalNotFound, alMultipleCovers model.Album
+	var alOnlyEmbed, alEmbedNotFound, alOnlyExternal, alExternalNotFound, alMultipleCovers, alSingleDisc model.Album
 	var arMultipleCovers model.Artist
 	var mfWithEmbed, mfAnotherWithEmbed, mfWithoutEmbed, mfCorruptedCover model.MediaFile

@@ -35,14 +37,20 @@ 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"}}
+		alOnlyExternal = model.Album{ID: "444", Name: "Only external", FolderIDs: []string{"f1"}, Discs: model.Discs{1: "", 2: ""}}
 		alExternalNotFound = model.Album{ID: "555", Name: "External not found", FolderIDs: []string{"f2"}}
+		alSingleDisc = model.Album{ID: "888", Name: "Single disc", FolderIDs: []string{"f1"}, Discs: model.Discs{1: ""}}
 		arMultipleCovers = model.Artist{ID: "777", Name: "All options"}
 		alMultipleCovers = model.Album{
 			ID:            "666",
@@ -142,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,
@@ -167,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"),
@@ -190,6 +246,7 @@ var _ = Describe("Artwork", func() {
 				ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
 					alOnlyEmbed,
 					alOnlyExternal,
+					alSingleDisc,
 				})
 				ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 					mfWithEmbed,
@@ -233,8 +290,137 @@ var _ = Describe("Artwork", func() {
 				Expect(err).ToNot(HaveOccurred())
 				Expect(path).To(Equal("al-444_0"))
 			})
+			It("falls back to disc cover art when media file has a disc number on a multi-disc album", func() {
+				mfWithDisc := model.MediaFile{ID: "46", Path: "tests/fixtures/test.ogg", AlbumID: "444", DiscNumber: 2}
+				Expect(ds.MediaFile(ctx).(*tests.MockMediaFileRepo).Put(&mfWithDisc)).To(Succeed())
+
+				aw, err := newMediafileArtworkReader(ctx, aw, model.MustParseArtworkID("mf-"+mfWithDisc.ID))
+				Expect(err).ToNot(HaveOccurred())
+				_, path, err := aw.Reader(ctx)
+				Expect(err).ToNot(HaveOccurred())
+				// Should fall back to disc art, which itself falls back to album art
+				Expect(path).To(Equal("dc-444:2_0"))
+			})
+			It("falls back to album cover art for single-disc albums even with a disc number", func() {
+				mfOnSingleDisc := model.MediaFile{ID: "47", Path: "tests/fixtures/test.ogg", AlbumID: "888", DiscNumber: 1}
+				Expect(ds.MediaFile(ctx).(*tests.MockMediaFileRepo).Put(&mfOnSingleDisc)).To(Succeed())
+
+				aw, err := newMediafileArtworkReader(ctx, aw, model.MustParseArtworkID("mf-"+mfOnSingleDisc.ID))
+				Expect(err).ToNot(HaveOccurred())
+				_, path, err := aw.Reader(ctx)
+				Expect(err).ToNot(HaveOccurred())
+				// Single-disc album should skip disc art and go straight to album art
+				Expect(path).To(Equal("al-888_0"))
+			})
 		})
 	})
+	Describe("playlistArtworkReader", func() {
+		Describe("findPlaylistSidecarPath", func() {
+			It("discovers sidecar image next to playlist file", func() {
+				tmpDir := GinkgoT().TempDir()
+				plsPath := filepath.Join(tmpDir, "MyPlaylist.m3u")
+				imgPath := filepath.Join(tmpDir, "MyPlaylist.jpg")
+				Expect(os.WriteFile(plsPath, []byte("#EXTM3U\n"), 0600)).To(Succeed())
+				Expect(os.WriteFile(imgPath, []byte("fake image"), 0600)).To(Succeed())
+
+				result := findPlaylistSidecarPath(GinkgoT().Context(), plsPath)
+				Expect(result).To(Equal(imgPath))
+			})
+
+			It("returns empty string when no sidecar image exists", func() {
+				tmpDir := GinkgoT().TempDir()
+				plsPath := filepath.Join(tmpDir, "MyPlaylist.m3u")
+				Expect(os.WriteFile(plsPath, []byte("#EXTM3U\n"), 0600)).To(Succeed())
+
+				result := findPlaylistSidecarPath(GinkgoT().Context(), plsPath)
+				Expect(result).To(BeEmpty())
+			})
+
+			It("returns empty string when playlist has no path", func() {
+				result := findPlaylistSidecarPath(GinkgoT().Context(), "")
+				Expect(result).To(BeEmpty())
+			})
+
+			It("finds sidecar with different case base name", func() {
+				tmpDir := GinkgoT().TempDir()
+				plsPath := filepath.Join(tmpDir, "myplaylist.m3u")
+				imgPath := filepath.Join(tmpDir, "MyPlaylist.jpg")
+				Expect(os.WriteFile(plsPath, []byte("#EXTM3U\n"), 0600)).To(Succeed())
+				Expect(os.WriteFile(imgPath, []byte("fake image"), 0600)).To(Succeed())
+
+				result := findPlaylistSidecarPath(GinkgoT().Context(), plsPath)
+				Expect(result).To(Equal(imgPath))
+			})
+		})
+
+		Describe("fromPlaylistExternalImage", func() {
+			It("opens local path from ExternalImageURL", func() {
+				tmpDir := GinkgoT().TempDir()
+				imgPath := filepath.Join(tmpDir, "cover.jpg")
+				Expect(os.WriteFile(imgPath, []byte("external image data"), 0600)).To(Succeed())
+
+				reader := &playlistArtworkReader{
+					pl: model.Playlist{ExternalImageURL: imgPath},
+				}
+				r, path, err := reader.fromPlaylistExternalImage(ctx)()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(imgPath))
+				data, _ := io.ReadAll(r)
+				Expect(string(data)).To(Equal("external image data"))
+				r.Close()
+			})
+
+			It("returns nil when ExternalImageURL is empty", func() {
+				reader := &playlistArtworkReader{
+					pl: model.Playlist{ExternalImageURL: ""},
+				}
+				r, path, err := reader.fromPlaylistExternalImage(ctx)()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).To(BeNil())
+				Expect(path).To(BeEmpty())
+			})
+
+			It("returns error when local file does not exist", func() {
+				reader := &playlistArtworkReader{
+					pl: model.Playlist{ExternalImageURL: "/non/existent/path/cover.jpg"},
+				}
+				r, _, err := reader.fromPlaylistExternalImage(ctx)()
+				Expect(err).To(HaveOccurred())
+				Expect(r).To(BeNil())
+			})
+
+			It("skips HTTP URL when EnableM3UExternalAlbumArt is false", func() {
+				conf.Server.EnableM3UExternalAlbumArt = false
+
+				reader := &playlistArtworkReader{
+					pl: model.Playlist{ExternalImageURL: "https://example.com/cover.jpg"},
+				}
+				r, path, err := reader.fromPlaylistExternalImage(ctx)()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).To(BeNil())
+				Expect(path).To(BeEmpty())
+			})
+
+			It("still opens local path when EnableM3UExternalAlbumArt is false", func() {
+				conf.Server.EnableM3UExternalAlbumArt = false
+
+				tmpDir := GinkgoT().TempDir()
+				imgPath := filepath.Join(tmpDir, "cover.jpg")
+				Expect(os.WriteFile(imgPath, []byte("local image"), 0600)).To(Succeed())
+
+				reader := &playlistArtworkReader{
+					pl: model.Playlist{ExternalImageURL: imgPath},
+				}
+				r, path, err := reader.fromPlaylistExternalImage(ctx)()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(imgPath))
+				r.Close()
+			})
+		})
+	})
+
 	Describe("resizedArtworkReader", func() {
 		BeforeEach(func() {
 			folderRepo.result = []model.Folder{{
@@ -246,7 +432,7 @@ var _ = Describe("Artwork", func() {
 			})
 		})
 		When("Square is false", func() {
-			It("returns a PNG 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())
@@ -257,7 +443,7 @@ var _ = Describe("Artwork", func() {
 				Expect(img.Bounds().Size().X).To(Equal(15))
 				Expect(img.Bounds().Size().Y).To(Equal(15))
 			})
-			It("returns a JPEG if original image is not a PNG", func() {
+			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())
@@ -273,15 +459,18 @@ var _ = Describe("Artwork", func() {
 			var alCover model.Album

 			DescribeTable("resize",
-				func(format string, landscape bool, size int) {
-					coverFileName := "cover." + format
-					dirName := createImage(format, landscape, size)
+				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}}}
+					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,
 					})
@@ -292,16 +481,100 @@ var _ = Describe("Artwork", func() {

 					img, format, err := image.Decode(r)
 					Expect(err).ToNot(HaveOccurred())
-					Expect(format).To(Equal("png"))
+					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", false, 200),
-				Entry("landscape png image", "png", true, 200),
-				Entry("portrait jpg image", "jpg", false, 200),
-				Entry("landscape jpg image", "jpg", true, 200),
+				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)
+				Expect(err).ToNot(HaveOccurred())
+
+				img, format, err := image.Decode(r)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(format).To(Equal("webp"))
+				Expect(img.Bounds().Size().X).To(Equal(15))
+				Expect(img.Bounds().Size().Y).To(Equal(15))
+			})
+			It("returns WebP 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("webp"))
+				Expect(err).ToNot(HaveOccurred())
+				Expect(img.Bounds().Size().X).To(Equal(200))
+				Expect(img.Bounds().Size().Y).To(Equal(200))
+			})
+		})
+		When("EnableWebPEncoding is false and square is false", func() {
+			BeforeEach(func() {
+				conf.Server.EnableWebPEncoding = false
+			})
+			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 a JPG", 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(err).ToNot(HaveOccurred())
+				Expect(format).To(Equal("jpeg"))
+				Expect(img.Bounds().Size().X).To(Equal(200))
+				Expect(img.Bounds().Size().Y).To(Equal(200))
+			})
+		})
+		When("EnableWebPEncoding is false and square is true", func() {
+			var alCover model.Album
+
+			BeforeEach(func() {
+				conf.Server.EnableWebPEncoding = false
+			})
+			It("returns PNG for square mode", func() {
+				dirName := createImage("png", false, 200)
+				alCover = model.Album{
+					ID:        "444",
+					Name:      "Only external",
+					FolderIDs: []string{"tmp"},
+				}
+				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"
+				r, _, err := aw.Get(context.Background(), alCover.CoverArtID(), 200, true)
+				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(200))
+				Expect(img.Bounds().Size().Y).To(Equal(200))
+			})
+		})
 		When("Requested size is larger than original", func() {
 			It("clamps size to original dimensions", func() {
 				conf.Server.CoverArtPriority = "front.png"
@@ -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
+}
@@ -0,0 +1,37 @@
+package artwork
+
+import (
+	"bytes"
+	"fmt"
+	"image"
+	_ "image/jpeg"
+	_ "image/png"
+	"testing"
+)
+
+func BenchmarkImageDecode(b *testing.B) {
+	sizes := []int{300, 1000, 3000}
+	formats := []struct {
+		name string
+		gen  func(tb testing.TB, w, h int) []byte
+	}{
+		{"jpeg", func(tb testing.TB, w, h int) []byte { return generateJPEG(tb, w, h, 75) }},
+		{"png", func(tb testing.TB, w, h int) []byte { return generatePNG(tb, w, h) }},
+	}
+
+	for _, format := range formats {
+		for _, size := range sizes {
+			data := format.gen(b, size, size)
+			b.Run(fmt.Sprintf("%s/%dx%d", format.name, size, size), func(b *testing.B) {
+				b.SetBytes(int64(len(data)))
+				b.ResetTimer()
+				for i := 0; i < b.N; i++ {
+					_, _, err := image.Decode(bytes.NewReader(data))
+					if err != nil {
+						b.Fatal(err)
+					}
+				}
+			})
+		}
+	}
+}
@@ -0,0 +1,189 @@
+package artwork
+
+import (
+	"context"
+	"fmt"
+	"image/jpeg"
+	"io"
+	"os"
+	"path/filepath"
+	"runtime"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/cache"
+)
+
+// setupE2EBenchmark creates an artwork instance with a real album cover image on disk,
+// backed by either a real file cache or disabled cache depending on cacheSize.
+// Note: This benchmarks artwork.Get() directly (not the full HTTP handler), which covers
+// the critical path (source selection, decode, resize, encode, cache). This is a deliberate
+// spec deviation — the full HTTP round-trip benchmark requires significant infrastructure
+// (DB, scanner, fake filesystem) and can be added later if HTTP overhead proves significant.
+//
+// Depends on fakeFolderRepo defined in reader_artist_test.go (same package, compiled together).
+func setupE2EBenchmark(b *testing.B, cacheSize string) (Artwork, model.ArtworkID, func()) {
+	b.Helper()
+	cleanup := configtest.SetupConfig()
+	b.Cleanup(cleanup)
+
+	tmpDir, err := os.MkdirTemp("", "artwork-bench-*")
+	if err != nil {
+		b.Fatal(err)
+	}
+
+	// Create a realistic cover image on disk
+	coverPath := filepath.Join(tmpDir, "cover.jpg")
+	coverImg := generateGradientImage(1000, 1000)
+	f, err := os.Create(coverPath)
+	if err != nil {
+		b.Fatal(err)
+	}
+	if err := jpeg.Encode(f, coverImg, &jpeg.Options{Quality: 90}); err != nil {
+		f.Close()
+		b.Fatal(err)
+	}
+	f.Close()
+
+	// Configure cache
+	conf.Server.ImageCacheSize = cacheSize
+	conf.Server.CacheFolder = tmpDir
+	conf.Server.CoverArtQuality = 75
+	conf.Server.CoverArtPriority = "cover.*"
+
+	// Set up mock data store with album pointing to our cover.
+	// Set UpdatedAt so CoverArtID().LastUpdate is consistent across calls.
+	album := model.Album{
+		ID:        "bench-album-1",
+		Name:      "Benchmark Album",
+		FolderIDs: []string{"f1"},
+		UpdatedAt: time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC),
+	}
+	folderRepo := &fakeFolderRepo{
+		result: []model.Folder{{
+			Path:       tmpDir,
+			ImageFiles: []string{"cover.jpg"},
+		}},
+	}
+	ds := &tests.MockDataStore{
+		MockedTranscoding: &tests.MockTranscodingRepo{},
+		MockedFolder:      folderRepo,
+	}
+	ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{album})
+
+	artID := album.CoverArtID()
+
+	imgCache := cache.NewFileCache("BenchImage", cacheSize, "bench-images", 0,
+		func(ctx context.Context, arg cache.Item) (io.Reader, error) {
+			r, _, err := arg.(artworkReader).Reader(ctx)
+			return r, err
+		})
+
+	// Wait for cache init if enabled
+	if cacheSize != "0" {
+		for !imgCache.Available(context.Background()) && !imgCache.Disabled(context.Background()) {
+			runtime.Gosched() // Yield to allow background init goroutine to run
+		}
+	}
+
+	ffmpeg := tests.NewMockFFmpeg("fallback content")
+	aw := NewArtwork(ds, imgCache, ffmpeg, nil)
+
+	cleanupAll := func() {
+		os.RemoveAll(tmpDir)
+	}
+	return aw, artID, cleanupAll
+}
+
+func BenchmarkArtworkGetE2E(b *testing.B) {
+	cacheConfigs := []struct {
+		name      string
+		cacheSize string
+	}{
+		{"no_cache", "0"},
+		{"with_cache", "100MB"},
+	}
+	sizes := []int{0, 300}
+
+	for _, cc := range cacheConfigs {
+		for _, size := range sizes {
+			b.Run(fmt.Sprintf("%s/size_%d", cc.name, size), func(b *testing.B) {
+				aw, artID, cleanup := setupE2EBenchmark(b, cc.cacheSize)
+				defer cleanup()
+
+				// Warm the cache on first call if cache is enabled
+				if cc.cacheSize != "0" {
+					r, _, err := aw.Get(context.Background(), artID, size, size > 0)
+					if err != nil {
+						b.Fatal(err)
+					}
+					_, _ = io.ReadAll(r)
+					r.Close()
+				}
+
+				b.ResetTimer()
+				for i := 0; i < b.N; i++ {
+					r, _, err := aw.Get(context.Background(), artID, size, size > 0)
+					if err != nil {
+						b.Fatal(err)
+					}
+					_, _ = io.ReadAll(r)
+					r.Close()
+				}
+			})
+		}
+	}
+}
+
+func BenchmarkArtworkGetE2EConcurrent(b *testing.B) {
+	cacheConfigs := []struct {
+		name      string
+		cacheSize string
+	}{
+		{"no_cache", "0"},
+		{"with_cache", "100MB"},
+	}
+	concurrencyLevels := []int{10, 50}
+
+	for _, cc := range cacheConfigs {
+		for _, n := range concurrencyLevels {
+			b.Run(fmt.Sprintf("%s/goroutines_%d", cc.name, n), func(b *testing.B) {
+				aw, artID, cleanup := setupE2EBenchmark(b, cc.cacheSize)
+				defer cleanup()
+
+				// Warm cache
+				if cc.cacheSize != "0" {
+					r, _, _ := aw.Get(context.Background(), artID, 300, true)
+					if r != nil {
+						_, _ = io.ReadAll(r)
+						r.Close()
+					}
+				}
+
+				b.ResetTimer()
+				for i := 0; i < b.N; i++ {
+					var wg sync.WaitGroup
+					wg.Add(n)
+					for g := 0; g < n; g++ {
+						go func() {
+							defer wg.Done()
+							r, _, err := aw.Get(context.Background(), artID, 300, true)
+							if err != nil {
+								b.Error(err)
+								return
+							}
+							_, _ = io.ReadAll(r)
+							r.Close()
+						}()
+					}
+					wg.Wait()
+				}
+			})
+		}
+	}
+}
@@ -0,0 +1,40 @@
+package artwork
+
+import (
+	"bytes"
+	"fmt"
+	"image/jpeg"
+	"image/png"
+	"testing"
+)
+
+func BenchmarkImageEncode(b *testing.B) {
+	img := generateGradientImage(300, 300)
+
+	jpegQualities := []int{60, 75, 90}
+	for _, q := range jpegQualities {
+		b.Run(fmt.Sprintf("jpeg/q%d/300x300", q), func(b *testing.B) {
+			var buf bytes.Buffer
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				buf.Reset()
+				if err := jpeg.Encode(&buf, img, &jpeg.Options{Quality: q}); err != nil {
+					b.Fatal(err)
+				}
+			}
+			b.ReportMetric(float64(buf.Len()), "bytes")
+		})
+	}
+
+	b.Run("png/300x300", func(b *testing.B) {
+		var buf bytes.Buffer
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			buf.Reset()
+			if err := png.Encode(&buf, img); err != nil {
+				b.Fatal(err)
+			}
+		}
+		b.ReportMetric(float64(buf.Len()), "bytes")
+	})
+}
@@ -0,0 +1,47 @@
+package artwork
+
+import (
+	"bytes"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"image/png"
+	"testing"
+)
+
+// generateJPEG creates a JPEG image of the given dimensions with a gradient pattern.
+// The gradient ensures the image has realistic entropy (not trivially compressible).
+func generateJPEG(t testing.TB, width, height, quality int) []byte {
+	t.Helper()
+	img := generateGradientImage(width, height)
+	var buf bytes.Buffer
+	if err := jpeg.Encode(&buf, img, &jpeg.Options{Quality: quality}); err != nil {
+		t.Fatal(err)
+	}
+	return buf.Bytes()
+}
+
+// generatePNG creates a PNG image of the given dimensions with a gradient pattern.
+func generatePNG(t testing.TB, width, height int) []byte {
+	t.Helper()
+	img := generateGradientImage(width, height)
+	var buf bytes.Buffer
+	if err := png.Encode(&buf, img); err != nil {
+		t.Fatal(err)
+	}
+	return buf.Bytes()
+}
+
+// generateGradientImage creates an RGBA image with a diagonal gradient pattern.
+func generateGradientImage(width, height int) *image.RGBA {
+	img := image.NewRGBA(image.Rect(0, 0, width, height))
+	for y := 0; y < height; y++ {
+		for x := 0; x < width; x++ {
+			r := uint8((x * 255) / width)
+			g := uint8((y * 255) / height)
+			b := uint8(((x + y) * 255) / (width + height))
+			img.Set(x, y, color.RGBA{R: r, G: g, B: b, A: 255})
+		}
+	}
+	return img
+}
@@ -0,0 +1,50 @@
+package artwork
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+)
+
+func BenchmarkResizeFullPipeline(b *testing.B) {
+	cleanup := configtest.SetupConfig()
+	b.Cleanup(cleanup)
+	conf.Server.CoverArtQuality = 75
+
+	sourceSizes := []int{1000, 3000}
+	targetSize := 300
+
+	for _, srcSize := range sourceSizes {
+		jpegData := generateJPEG(b, srcSize, srcSize, 90)
+
+		b.Run(fmt.Sprintf("jpeg/%dx%d_to_%d", srcSize, srcSize, targetSize), func(b *testing.B) {
+			b.SetBytes(int64(len(jpegData)))
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				result, _, err := resizeStaticImage(jpegData, targetSize, false)
+				if err != nil {
+					b.Fatal(err)
+				}
+				if result == nil {
+					b.Fatal("expected non-nil resized image")
+				}
+			}
+		})
+
+		b.Run(fmt.Sprintf("jpeg/%dx%d_to_%d_square", srcSize, srcSize, targetSize), func(b *testing.B) {
+			b.SetBytes(int64(len(jpegData)))
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				result, _, err := resizeStaticImage(jpegData, targetSize, true)
+				if err != nil {
+					b.Fatal(err)
+				}
+				if result == nil {
+					b.Fatal("expected non-nil resized image")
+				}
+			}
+		})
+	}
+}
@@ -0,0 +1,38 @@
+package artwork
+
+import (
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"go.senan.xyz/taglib"
+)
+
+func BenchmarkTagExtraction(b *testing.B) {
+	// Ensure working directory is the project root (tests.Init not called with -run='^$')
+	_, file, _, ok := runtime.Caller(0)
+	if !ok {
+		b.Fatal("runtime.Caller failed")
+	}
+	appPath, _ := filepath.Abs(filepath.Join(filepath.Dir(file), "..", ".."))
+
+	// Use existing test fixture with embedded artwork
+	testFile := filepath.Join(appPath, "tests/fixtures/artist/an-album/test.mp3")
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		f, err := taglib.OpenReadOnly(testFile, taglib.WithReadStyle(taglib.ReadStyleFast))
+		if err != nil {
+			b.Fatal(err)
+		}
+		images := f.Properties().Images
+		if len(images) == 0 {
+			b.Fatal("no images found in test file")
+		}
+		data, err := f.Image(0)
+		if err != nil || len(data) == 0 {
+			b.Fatal("failed to extract image data")
+		}
+		f.Close()
+	}
+}
@@ -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) {
@@ -132,7 +133,7 @@ func (a *cacheWarmer) waitSignal(ctx context.Context, timeout time.Duration) {
 func (a *cacheWarmer) processBatch(ctx context.Context, batch []model.ArtworkID) {
 	log.Trace(ctx, "PreCaching a new batch of artwork", "batchSize", len(batch))
 	input := pl.FromSlice(ctx, batch)
-	errs := pl.Sink(ctx, 2, input, a.doCacheImage)
+	errs := pl.Sink(ctx, 4, input, a.doCacheImage)
 	for err := range errs {
 		log.Debug(ctx, "Error warming cache", err)
 	}
@@ -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()

-	r, _, err := a.artwork.Get(ctx, id, consts.UICoverArtSize, true)
+	size := a.coverArtSize
+	r, _, err := a.artwork.Get(ctx, id, size, true)
 	if err != nil {
-		return fmt.Errorf("caching id='%s': %w", id, err)
+		return fmt.Errorf("caching id='%s', size=%d: %w", id, size, err)
 	}
-	defer r.Close()
 	_, err = io.Copy(io.Discard, r)
-	if err != nil {
-		return err
-	}
-	return nil
+	r.Close()
+	return err
 }

 func NoopCacheWarmer() CacheWarmer {
@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"strings"
+	"sync"
 	"sync/atomic"
 	"time"

@@ -173,20 +174,42 @@ var _ = Describe("CacheWarmer", func() {
 				return len(cw.buffer)
 			}).Should(Equal(0))
 		})
+
+		It("pre-caches UICoverArtSize", func() {
+			cw := NewCacheWarmer(aw, fc).(*cacheWarmer)
+			cw.PreCache(model.MustParseArtworkID("al-1"))
+
+			Eventually(func() []int {
+				return aw.getCachedSizes()
+			}).Should(ContainElements(conf.Server.UICoverArtSize))
+		})
 	})
 })

 type mockArtwork struct {
-	err error
+	err         error
+	mu          sync.Mutex
+	cachedSizes []int
 }

 func (m *mockArtwork) Get(ctx context.Context, artID model.ArtworkID, size int, square bool) (io.ReadCloser, time.Time, error) {
 	if m.err != nil {
 		return nil, time.Time{}, m.err
 	}
+	m.mu.Lock()
+	m.cachedSizes = append(m.cachedSizes, size)
+	m.mu.Unlock()
 	return io.NopCloser(strings.NewReader("test")), time.Now(), nil
 }

+func (m *mockArtwork) getCachedSizes() []int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	result := make([]int, len(m.cachedSizes))
+	copy(result, m.cachedSizes)
+	return result
+}
+
 func (m *mockArtwork) GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (io.ReadCloser, time.Time, error) {
 	return m.Get(ctx, model.ArtworkID{}, size, square)
 }
@@ -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")))
+		})
+	})
+})
@@ -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]
+}
@@ -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")))
+		})
+	})
+})
@@ -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)
@@ -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]
+}
@@ -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
+}
@@ -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())
+		})
+	})
+})
@@ -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]
+}
@@ -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
+}
@@ -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())
+	})
+})
@@ -4,30 +4,31 @@ import (
 	"cmp"
 	"context"
 	"crypto/md5"
+	"errors"
 	"fmt"
 	"io"
-	"path/filepath"
+	"path"
 	"slices"
 	"strings"
 	"time"

 	"github.com/Masterminds/squirrel"
-	"github.com/maruel/natural"
 	"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"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/natural"
 )

 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) {
@@ -39,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) {
@@ -57,10 +62,11 @@ func newAlbumArtworkReader(ctx context.Context, artwork *artwork, artID model.Ar
 }

 func (a *albumArtworkReader) Key() string {
-	var hash [16]byte
+	hashInput := conf.Server.CoverArtPriority
 	if conf.Server.EnableExternalServices {
-		hash = md5.Sum([]byte(conf.Server.Agents + conf.Server.CoverArtPriority))
+		hashInput = conf.Server.Agents + hashInput
 	}
+	hash := md5.Sum([]byte(hashInput))
 	return fmt.Sprintf(
 		"%s.%x.%t",
 		a.cacheKey.Key(),
@@ -69,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) {
@@ -83,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
@@ -103,17 +112,42 @@ func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...mo
 	if err != nil {
 		return nil, nil, nil, err
 	}
+
+	folderIDSet := make(map[string]bool, len(folderIDs))
+	for _, id := range folderIDs {
+		folderIDSet[id] = true
+	}
+
+	// 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 != "" {
+		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)
+			}
+		}
+	}
+
 	var paths []string
 	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))
 		}
 	}

@@ -125,23 +159,48 @@ func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...mo
 	return paths, imgFiles, &updatedAt, nil
 }

-// 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.
+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) == 0 {
+		return ""
+	}
+	parentID := folders[0].ParentID
+	if parentID == "" || folderIDSet[parentID] {
+		return ""
+	}
+	for _, f := range folders[1:] {
+		if f.ParentID != parentID {
+			return ""
+		}
+	}
+	return parentID
+}
+
+// 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),
 	)
 }
@@ -2,7 +2,7 @@ package artwork

 import (
 	"context"
-	"path/filepath"
+	"errors"
 	"time"

 	"github.com/navidrome/navidrome/model"
@@ -68,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() {
@@ -91,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() {
@@ -112,9 +112,245 @@ 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() {
+			// Simulates: Artist/Album/cover.jpg with tracks in Artist/Album/CD1/ and Artist/Album/CD2/
+			repo.result = []model.Folder{
+				{
+					ID:              "folder1",
+					Path:            "Artist/Album",
+					Name:            "CD1",
+					ParentID:        "parentFolder",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{},
+				},
+				{
+					ID:              "folder2",
+					Path:            "Artist/Album",
+					Name:            "CD2",
+					ParentID:        "parentFolder",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{},
+				},
+			}
+			repo.parentResult = &model.Folder{
+				ID:              "parentFolder",
+				Path:            "Artist",
+				Name:            "Album",
+				ImagesUpdatedAt: expectedAt,
+				ImageFiles:      []string{"cover.jpg", "back.jpg"},
+			}
+
+			_, imgFiles, imagesUpdatedAt, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(*imagesUpdatedAt).To(Equal(expectedAt))
+			Expect(imgFiles).To(HaveLen(2))
+			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() {
+			// When the parent folder is already one of the album's folders, skip it
+			repo.result = []model.Folder{
+				{
+					ID:              "folder1",
+					Path:            "Artist",
+					Name:            "Album",
+					ParentID:        "folder2",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{"cover.jpg"},
+				},
+				{
+					ID:              "folder2",
+					Path:            "",
+					Name:            "Artist",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{},
+				},
+			}
+
+			_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(imgFiles).To(HaveLen(1))
+			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))
+		})
+
+		It("does not query parent when folders have different parents", func() {
+			// When album folders span different parents, don't search any parent
+			repo.result = []model.Folder{
+				{
+					ID:              "folder1",
+					Path:            "Artist1/Album",
+					Name:            "part1",
+					ParentID:        "parentA",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{"cover.jpg"},
+				},
+				{
+					ID:              "folder2",
+					Path:            "Artist2/Album",
+					Name:            "part2",
+					ParentID:        "parentB",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{},
+				},
+			}
+
+			_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(imgFiles).To(HaveLen(1))
+			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 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",
+					Path:            "Artist",
+					Name:            "Album",
+					ParentID:        "artistFolder",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{"cover.jpg"},
+				},
+			}
+
+			_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(imgFiles).To(HaveLen(1))
+			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{
+				{
+					ID:              "folder1",
+					Path:            "Artist/Album",
+					Name:            "CD1",
+					ParentID:        "parentFolder",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{"cover.jpg"},
+				},
+				{
+					ID:              "folder2",
+					Path:            "Artist/Album",
+					Name:            "CD2",
+					ParentID:        "parentFolder",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{},
+				},
+			}
+			repo.getErr = errors.New("db connection failed")
+
+			_, _, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).To(MatchError("db connection failed"))
+			Expect(repo.getCallCount).To(Equal(1))
+		})
+
+		It("continues gracefully when parent folder is not found", func() {
+			// Parent folder may have been deleted; should log a warning and continue
+			repo.result = []model.Folder{
+				{
+					ID:              "folder1",
+					Path:            "Artist/Album",
+					Name:            "CD1",
+					ParentID:        "missingParent",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{"cover.jpg"},
+				},
+				{
+					ID:              "folder2",
+					Path:            "Artist/Album",
+					Name:            "CD2",
+					ParentID:        "missingParent",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{},
+				},
+			}
+			// parentResult is nil, so Get will return ErrNotFound
+
+			_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(imgFiles).To(HaveLen(1))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/CD1/cover.jpg"))
+			Expect(repo.getCallCount).To(Equal(1))
 		})
 	})
 })
@@ -7,6 +7,7 @@ import (
 	"io"
 	"io/fs"
 	"os"
+	"path"
 	"path/filepath"
 	"slices"
 	"strings"
@@ -29,11 +30,13 @@ const (

 type artistReader struct {
 	cacheKey
-	a            *artwork
-	provider     external.Provider
-	artist       model.Artist
-	artistFolder string
-	imgFiles     []string
+	a                *artwork
+	provider         external.Provider
+	artist           model.Artist
+	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) {
@@ -59,27 +62,46 @@ 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
 	//a.cacheKey.lastUpdate = ar.ExternalInfoUpdatedAt

 	a.cacheKey.lastUpdate = *imagesUpdatedAt
+	if ar.UpdatedAt != nil && ar.UpdatedAt.After(a.cacheKey.lastUpdate) {
+		a.cacheKey.lastUpdate = *ar.UpdatedAt
+	}
 	if artistFolderLastUpdate.After(a.cacheKey.lastUpdate) {
 		a.cacheKey.lastUpdate = artistFolderLastUpdate
 	}
+	if conf.Server.ArtistImageFolder != "" && strings.Contains(strings.ToLower(conf.Server.ArtistArtPriority), "image-folder") {
+		a.imgFolderImgPath = findImageInArtistFolder(conf.Server.ArtistImageFolder, ar.MbzArtistID, ar.Name)
+		if a.imgFolderImgPath != "" {
+			if info, err := os.Stat(a.imgFolderImgPath); err == nil && info.ModTime().After(a.cacheKey.lastUpdate) {
+				a.cacheKey.lastUpdate = info.ModTime()
+			}
+		}
+	}
 	a.cacheKey.artID = artID
 	return a, nil
 }

 func (a *artistReader) Key() string {
-	hash := md5.Sum([]byte(conf.Server.Agents + conf.Server.Spotify.ID))
+	hash := md5.Sum([]byte(conf.Server.Agents))
 	return fmt.Sprintf(
 		"%s.%t.%x",
 		a.cacheKey.Key(),
@@ -93,10 +115,15 @@ func (a *artistReader) LastUpdated() time.Time {
 }

 func (a *artistReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
-	var ff = a.fromArtistArtPriority(ctx, conf.Server.ArtistArtPriority)
+	ff := []sourceFunc{a.fromArtistUploadedImage()}
+	ff = append(ff, a.fromArtistArtPriority(ctx, conf.Server.ArtistArtPriority)...)
 	return selectImageReader(ctx, a.artID, ff...)
 }

+func (a *artistReader) fromArtistUploadedImage() sourceFunc {
+	return fromLocalFile(a.artist.UploadedImagePath())
+}
+
 func (a *artistReader) fromArtistArtPriority(ctx context.Context, priority string) []sourceFunc {
 	var ff []sourceFunc
 	for pattern := range strings.SplitSeq(strings.ToLower(priority), ",") {
@@ -104,39 +131,65 @@ func (a *artistReader) fromArtistArtPriority(ctx context.Context, priority strin
 		switch {
 		case pattern == "external":
 			ff = append(ff, fromArtistExternalSource(ctx, a.artist, a.provider))
+		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
 	}

@@ -153,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) {
@@ -196,3 +261,51 @@ func loadArtistFolder(ctx context.Context, ds model.DataStore, albums model.Albu
 	}
 	return folderPath, folders[0].ImagesUpdatedAt, nil
 }
+
+func (a *artistReader) fromArtistImageFolder(ctx context.Context) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		folder := conf.Server.ArtistImageFolder
+		if folder == "" {
+			return nil, "", nil
+		}
+		// Use cached path from newArtistArtworkReader if available,
+		// avoiding a second directory scan.
+		path := a.imgFolderImgPath
+		if path == "" {
+			path = findImageInArtistFolder(folder, a.artist.MbzArtistID, a.artist.Name)
+		}
+		if path == "" {
+			return nil, "", fmt.Errorf("no image found for artist %q in %s", a.artist.Name, folder)
+		}
+		f, err := os.Open(path)
+		if err != nil {
+			return nil, "", err
+		}
+		return f, path, nil
+	}
+}
+
+// findImageInArtistFolder scans a folder for an image file matching the artist's MBID or name
+// (case-insensitive). Returns the full path, or empty string if not found.
+func findImageInArtistFolder(folder, mbzArtistID, artistName string) string {
+	entries, err := os.ReadDir(folder)
+	if err != nil {
+		return ""
+	}
+	for _, candidate := range []string{mbzArtistID, artistName} {
+		if candidate == "" {
+			continue
+		}
+		for _, entry := range entries {
+			if entry.IsDir() {
+				continue
+			}
+			name := entry.Name()
+			base := strings.TrimSuffix(name, filepath.Ext(name))
+			if strings.EqualFold(base, candidate) && model.IsImageFile(name) {
+				return filepath.Join(folder, name)
+			}
+		}
+	}
+	return ""
+}
@@ -4,10 +4,13 @@ import (
 	"context"
 	"errors"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"time"

+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
@@ -64,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))
 			})
 		})
@@ -90,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))
 			})
 		})
@@ -115,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() {
@@ -132,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() {
@@ -149,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/
@@ -161,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() {
@@ -189,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() {
@@ -218,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() {
@@ -244,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() {
@@ -271,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() {
@@ -299,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() {
@@ -325,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() {
@@ -344,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() {
@@ -365,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() {
@@ -395,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() {
@@ -413,18 +442,283 @@ var _ = Describe("artistArtworkReader", func() {
 			})
 		})
 	})
+
+	Describe("fromArtistUploadedImage", func() {
+		var (
+			tempDir string
+			reader  *artistReader
+		)
+
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			tempDir = GinkgoT().TempDir()
+			conf.Server.DataFolder = tempDir
+
+			// Create the artwork/artist directory
+			Expect(os.MkdirAll(filepath.Join(tempDir, "artwork", "artist"), 0755)).To(Succeed())
+
+			reader = &artistReader{}
+		})
+
+		When("artist has an uploaded image", func() {
+			It("returns the uploaded image", func() {
+				imgPath := filepath.Join(tempDir, "artwork", "artist", "ar-1_test.jpg")
+				Expect(os.WriteFile(imgPath, []byte("uploaded artist image"), 0600)).To(Succeed())
+
+				reader.artist = model.Artist{ID: "ar-1", UploadedImage: "ar-1_test.jpg"}
+				sf := reader.fromArtistUploadedImage()
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(imgPath))
+
+				data, err := io.ReadAll(r)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(string(data)).To(Equal("uploaded artist image"))
+				r.Close()
+			})
+		})
+
+		When("artist has no uploaded image", func() {
+			It("returns nil reader (falls through)", func() {
+				reader.artist = model.Artist{ID: "ar-1"}
+				sf := reader.fromArtistUploadedImage()
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).To(BeNil())
+				Expect(path).To(BeEmpty())
+			})
+		})
+	})
+
+	Describe("fromArtistImageFolder", func() {
+		var (
+			ctx     context.Context
+			tempDir string
+			ar      *artistReader
+		)
+
+		BeforeEach(func() {
+			ctx = context.Background()
+			DeferCleanup(configtest.SetupConfig())
+			tempDir = GinkgoT().TempDir()
+			ar = &artistReader{}
+		})
+
+		When("ArtistImageFolder is not configured", func() {
+			It("returns nil (skips)", func() {
+				conf.Server.ArtistImageFolder = ""
+				ar.artist = model.Artist{Name: "Test Artist"}
+				sf := ar.fromArtistImageFolder(ctx)
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).To(BeNil())
+				Expect(path).To(BeEmpty())
+			})
+		})
+
+		When("image exists matching MBID", func() {
+			It("finds the image by MBID", func() {
+				conf.Server.ArtistImageFolder = tempDir
+				mbid := "f27ec8db-af05-4f36-916e-3d57f91ecf5e"
+				imgPath := filepath.Join(tempDir, mbid+".jpg")
+				Expect(os.WriteFile(imgPath, []byte("mbid image"), 0600)).To(Succeed())
+
+				ar.artist = model.Artist{Name: "Test Artist", MbzArtistID: mbid}
+				sf := ar.fromArtistImageFolder(ctx)
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(imgPath))
+
+				data, err := io.ReadAll(r)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(string(data)).To(Equal("mbid image"))
+				r.Close()
+			})
+		})
+
+		When("MBID match is case-insensitive", func() {
+			It("finds the image regardless of case", func() {
+				conf.Server.ArtistImageFolder = tempDir
+				mbid := "F27EC8DB-AF05-4F36-916E-3D57F91ECF5E"
+				imgPath := filepath.Join(tempDir, "f27ec8db-af05-4f36-916e-3d57f91ecf5e.png")
+				Expect(os.WriteFile(imgPath, []byte("mbid case image"), 0600)).To(Succeed())
+
+				ar.artist = model.Artist{Name: "Test Artist", MbzArtistID: mbid}
+				sf := ar.fromArtistImageFolder(ctx)
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(imgPath))
+				r.Close()
+			})
+		})
+
+		When("no MBID file exists but artist name file does", func() {
+			It("falls back to artist name match", func() {
+				conf.Server.ArtistImageFolder = tempDir
+				imgPath := filepath.Join(tempDir, "Test Artist.jpg")
+				Expect(os.WriteFile(imgPath, []byte("name image"), 0600)).To(Succeed())
+
+				ar.artist = model.Artist{Name: "Test Artist", MbzArtistID: "nonexistent-mbid"}
+				sf := ar.fromArtistImageFolder(ctx)
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(imgPath))
+
+				data, err := io.ReadAll(r)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(string(data)).To(Equal("name image"))
+				r.Close()
+			})
+		})
+
+		When("artist name match is case-insensitive", func() {
+			It("matches regardless of case", func() {
+				conf.Server.ArtistImageFolder = tempDir
+				imgPath := filepath.Join(tempDir, "test artist.jpg")
+				Expect(os.WriteFile(imgPath, []byte("case insensitive"), 0600)).To(Succeed())
+
+				ar.artist = model.Artist{Name: "Test Artist"}
+				sf := ar.fromArtistImageFolder(ctx)
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(imgPath))
+				r.Close()
+			})
+		})
+
+		When("both MBID and name files exist", func() {
+			It("prefers MBID over name match", func() {
+				conf.Server.ArtistImageFolder = tempDir
+				mbid := "f27ec8db-af05-4f36-916e-3d57f91ecf5e"
+				mbidPath := filepath.Join(tempDir, mbid+".jpg")
+				namePath := filepath.Join(tempDir, "Test Artist.jpg")
+				Expect(os.WriteFile(mbidPath, []byte("mbid image"), 0600)).To(Succeed())
+				Expect(os.WriteFile(namePath, []byte("name image"), 0600)).To(Succeed())
+
+				ar.artist = model.Artist{Name: "Test Artist", MbzArtistID: mbid}
+				sf := ar.fromArtistImageFolder(ctx)
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(mbidPath))
+
+				data, err := io.ReadAll(r)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(string(data)).To(Equal("mbid image"))
+				r.Close()
+			})
+		})
+
+		When("no matching image found", func() {
+			It("returns an error", func() {
+				conf.Server.ArtistImageFolder = tempDir
+				// Create an unrelated file
+				Expect(os.WriteFile(filepath.Join(tempDir, "other.jpg"), []byte("other"), 0600)).To(Succeed())
+
+				ar.artist = model.Artist{Name: "Test Artist"}
+				sf := ar.fromArtistImageFolder(ctx)
+				r, _, err := sf()
+				Expect(err).To(HaveOccurred())
+				Expect(r).To(BeNil())
+				Expect(err.Error()).To(ContainSubstring("no image found"))
+			})
+		})
+
+		When("cached imgFolderImgPath is set", func() {
+			It("uses cached path instead of scanning", func() {
+				conf.Server.ArtistImageFolder = tempDir
+				imgPath := filepath.Join(tempDir, "cached.jpg")
+				Expect(os.WriteFile(imgPath, []byte("cached image"), 0600)).To(Succeed())
+
+				ar.artist = model.Artist{Name: "Test Artist"}
+				ar.imgFolderImgPath = imgPath
+				sf := ar.fromArtistImageFolder(ctx)
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(imgPath))
+
+				data, err := io.ReadAll(r)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(string(data)).To(Equal("cached image"))
+				r.Close()
+			})
+		})
+	})
+
+	Describe("findImageInArtistFolder", func() {
+		var tempDir string
+
+		BeforeEach(func() {
+			tempDir = GinkgoT().TempDir()
+		})
+
+		When("matching file exists by MBID", func() {
+			It("returns the file path", func() {
+				mbid := "f27ec8db-af05-4f36-916e-3d57f91ecf5e"
+				imgPath := filepath.Join(tempDir, mbid+".jpg")
+				Expect(os.WriteFile(imgPath, []byte("image"), 0600)).To(Succeed())
+
+				path := findImageInArtistFolder(tempDir, mbid, "Test")
+				Expect(path).To(Equal(imgPath))
+			})
+		})
+
+		When("matching file exists by name", func() {
+			It("returns the file path", func() {
+				imgPath := filepath.Join(tempDir, "Test Artist.png")
+				Expect(os.WriteFile(imgPath, []byte("image"), 0600)).To(Succeed())
+
+				path := findImageInArtistFolder(tempDir, "", "Test Artist")
+				Expect(path).To(Equal(imgPath))
+			})
+		})
+
+		When("no matching file exists", func() {
+			It("returns empty string", func() {
+				path := findImageInArtistFolder(tempDir, "", "Unknown Artist")
+				Expect(path).To(BeEmpty())
+			})
+		})
+
+		When("folder does not exist", func() {
+			It("returns empty string", func() {
+				path := findImageInArtistFolder("/nonexistent/path", "", "Test")
+				Expect(path).To(BeEmpty())
+			})
+		})
+	})
 })

 type fakeFolderRepo struct {
 	model.FolderRepository
-	result []model.Folder
-	err    error
+	result       []model.Folder
+	parentResult *model.Folder
+	getErr       error
+	getCallCount int
+	err          error
 }

 func (f *fakeFolderRepo) GetAll(...model.QueryOptions) ([]model.Folder, error) {
 	return f.result, f.err
 }

+func (f *fakeFolderRepo) Get(id string) (*model.Folder, error) {
+	f.getCallCount++
+	if f.getErr != nil {
+		return nil, f.getErr
+	}
+	if f.parentResult != nil {
+		return f.parentResult, nil
+	}
+	return nil, model.ErrNotFound
+}
+
 type fakeDataStore struct {
 	model.DataStore
 	folderRepo *fakeFolderRepo
@@ -0,0 +1,267 @@
+package artwork
+
+import (
+	"context"
+	"crypto/md5"
+	"fmt"
+	"io"
+	"path"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core/ffmpeg"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+type discArtworkReader struct {
+	cacheKey
+	a              *artwork
+	album          model.Album
+	discNumber     int
+	imgFiles       []string        // library-relative, forward-slash, no leading slash
+	discFoldersRel map[string]bool // library-relative folder paths
+	isMultiFolder  bool
+	firstTrackRel  string // library-relative; for fromTag / ffmpeg via lib.Abs
+	lib            libraryView
+	updatedAt      *time.Time
+}
+
+func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID) (*discArtworkReader, error) {
+	albumID, discNumber, err := model.ParseDiscArtworkID(artID.ID)
+	if err != nil {
+		return nil, fmt.Errorf("invalid disc artwork id '%s': %w", artID.ID, err)
+	}
+
+	al, err := a.ds.Album(ctx).Get(albumID)
+	if err != nil {
+		return nil, err
+	}
+
+	_, imgFiles, imagesUpdatedAt, err := loadAlbumFoldersPaths(ctx, a.ds, *al)
+	if err != nil {
+		return nil, err
+	}
+
+	// Query mediafiles for this album + disc to find folder associations and first track
+	mfs, err := a.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Sort:    "track_number",
+		Order:   "ASC",
+		Filters: squirrel.Eq{"album_id": albumID, "disc_number": discNumber},
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	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 firstTrackRel == "" {
+			firstTrackRel = filepath.ToSlash(mf.Path)
+		}
+	}
+
+	// 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 {
+			folderIDs = append(folderIDs, id)
+		}
+		folders, err := a.ds.Folder(ctx).GetAll(model.QueryOptions{
+			Filters: squirrel.Eq{"folder.id": folderIDs},
+		})
+		if err != nil {
+			return nil, err
+		}
+		for _, f := range folders {
+			rel := strings.TrimPrefix(path.Join(f.Path, f.Name), "/")
+			discFoldersRel[rel] = true
+		}
+	}
+
+	isMultiFolder := len(al.FolderIDs) > 1
+
+	r := &discArtworkReader{
+		a:              a,
+		album:          *al,
+		discNumber:     discNumber,
+		imgFiles:       imgFiles,
+		discFoldersRel: discFoldersRel,
+		isMultiFolder:  isMultiFolder,
+		firstTrackRel:  firstTrackRel,
+		lib:            lib,
+		updatedAt:      imagesUpdatedAt,
+	}
+	r.cacheKey.artID = artID
+	if r.updatedAt != nil && r.updatedAt.After(al.UpdatedAt) {
+		r.cacheKey.lastUpdate = *r.updatedAt
+	} else {
+		r.cacheKey.lastUpdate = al.UpdatedAt
+	}
+	return r, nil
+}
+
+func (d *discArtworkReader) Key() string {
+	hash := md5.Sum([]byte(conf.Server.DiscArtPriority))
+	return fmt.Sprintf(
+		"%s.%x",
+		d.cacheKey.Key(),
+		hash,
+	)
+}
+
+func (d *discArtworkReader) LastUpdated() time.Time {
+	return d.lastUpdate
+}
+
+func (d *discArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
+	var ff = d.fromDiscArtPriority(ctx, d.a.ffmpeg, conf.Server.DiscArtPriority)
+	// Fallback to album cover art
+	albumArtID := model.NewArtworkID(model.KindAlbumArtwork, d.album.ID, &d.album.UpdatedAt)
+	ff = append(ff, fromAlbum(ctx, d.a, albumArtID))
+	return selectImageReader(ctx, d.cacheKey.artID, ff...)
+}
+
+func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmpeg.FFmpeg, priority string) []sourceFunc {
+	var ff []sourceFunc
+	for pattern := range strings.SplitSeq(strings.ToLower(priority), ",") {
+		pattern = strings.TrimSpace(pattern)
+		switch {
+		case pattern == "embedded":
+			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":
+			if subtitle := strings.TrimSpace(d.album.Discs[d.discNumber]); subtitle != "" {
+				ff = append(ff, d.fromDiscSubtitle(ctx, subtitle))
+			}
+		case len(d.imgFiles) > 0:
+			ff = append(ff, d.fromExternalFile(ctx, pattern))
+		}
+	}
+	return ff
+}
+
+// fromDiscSubtitle returns a sourceFunc that matches image files whose stem
+// (filename without extension) equals the disc subtitle (case-insensitive).
+func (d *discArtworkReader) fromDiscSubtitle(ctx context.Context, subtitle string) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		for _, file := range d.imgFiles {
+			name := path.Base(file)
+			stem := strings.TrimSuffix(name, path.Ext(name))
+			if !strings.EqualFold(stem, subtitle) {
+				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
+		}
+		return nil, "", fmt.Errorf("disc %d: no image file matching subtitle %q", d.discNumber, subtitle)
+	}
+}
+
+// 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) {
+	metaIdx := strings.IndexAny(pattern, globMetaChars)
+	if metaIdx < 0 {
+		return 0, false
+	}
+	prefix := pattern[:metaIdx]
+	if !strings.HasPrefix(filename, prefix) {
+		return 0, false
+	}
+
+	start := len(prefix)
+	end := start
+	for end < len(filename) && filename[end] >= '0' && filename[end] <= '9' {
+		end++
+	}
+	if end == start {
+		return 0, false
+	}
+	num, err := strconv.Atoi(filename[start:end])
+	if err != nil {
+		return 0, false
+	}
+	return num, true
+}
+
+// fromExternalFile returns a sourceFunc that matches image files against a glob
+// 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 := 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
+			}
+			if !match {
+				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
+				}
+			}
+
+			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
+			}
+			return f, file, nil
+		}
+		return nil, "", fmt.Errorf("disc %d: pattern '%s' not matched by files", d.discNumber, pattern)
+	}
+}
@@ -0,0 +1,492 @@
+package artwork
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Disc Artwork Reader", func() {
+	Describe("extractDiscNumber", func() {
+		DescribeTable("extracts disc number from filename based on glob pattern",
+			func(pattern, filename string, expectedNum int, expectedOk bool) {
+				num, ok := extractDiscNumber(pattern, filename)
+				Expect(ok).To(Equal(expectedOk))
+				if expectedOk {
+					Expect(num).To(Equal(expectedNum))
+				}
+			},
+			// Standard disc patterns
+			Entry("disc1.jpg", "disc*.*", "disc1.jpg", 1, true),
+			Entry("disc2.png", "disc*.*", "disc2.png", 2, true),
+			Entry("disc01.jpg", "disc*.*", "disc01.jpg", 1, true),
+			Entry("disc02.png", "disc*.*", "disc02.png", 2, true),
+			Entry("disc10.jpg", "disc*.*", "disc10.jpg", 10, true),
+
+			// CD patterns
+			Entry("cd1.jpg", "cd*.*", "cd1.jpg", 1, true),
+			Entry("cd02.png", "cd*.*", "cd02.png", 2, true),
+
+			// No number in filename
+			Entry("disc.jpg has no number", "disc*.*", "disc.jpg", 0, false),
+			Entry("cd.jpg has no number", "cd*.*", "cd.jpg", 0, false),
+
+			// Extra text after number
+			Entry("disc2-bonus.jpg", "disc*.*", "disc2-bonus.jpg", 2, true),
+			Entry("disc01_front.png", "disc*.*", "disc01_front.png", 1, true),
+
+			// Case insensitive (filename already lowered by caller)
+			Entry("Disc1.jpg lowered", "disc*.*", "disc1.jpg", 1, true),
+
+			// 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),
+		)
+	})
+
+	Describe("fromExternalFile", func() {
+		var (
+			ctx    context.Context
+			tmpDir string
+		)
+
+		BeforeEach(func() {
+			ctx = context.Background()
+			tmpDir = GinkgoT().TempDir()
+		})
+
+		// 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 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},
+				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(f1))
+		})
+
+		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},
+				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, 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},
+				discFoldersRel: map[string]bool{"album/cd1": true},
+				isMultiFolder:  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(f1))
+		})
+
+		It("prefers disc number over folder when number is present", 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},
+				discFoldersRel: map[string]bool{"album/cd1": true},
+				isMultiFolder:  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(f1))
+		})
+
+		It("does not match disc2.jpg when looking for disc 1", func() {
+			f1 := createFile("album/disc2.jpg")
+			reader := &discArtworkReader{
+				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*.*")
+			r, _, _ := sf()
+			Expect(r).To(BeNil())
+		})
+	})
+
+	Describe("fromDiscSubtitle", func() {
+		var (
+			ctx    context.Context
+			tmpDir string
+		)
+
+		BeforeEach(func() {
+			ctx = context.Background()
+			tmpDir = GinkgoT().TempDir()
+		})
+
+		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 relPath
+		}
+
+		It("matches image file whose stem equals the disc subtitle (case-insensitive)", func() {
+			f1 := createFile("album/The Blue Disc.jpg")
+			reader := &discArtworkReader{
+				discNumber: 1,
+				imgFiles:   []string{f1},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+			}
+
+			sf := reader.fromDiscSubtitle(ctx, "The Blue Disc")
+			r, path, err := sf()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(r).ToNot(BeNil())
+			r.Close()
+			Expect(path).To(Equal(f1))
+		})
+
+		It("matches case-insensitively", func() {
+			f1 := createFile("album/bonus tracks.png")
+			reader := &discArtworkReader{
+				discNumber: 2,
+				imgFiles:   []string{f1},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+			}
+
+			sf := reader.fromDiscSubtitle(ctx, "Bonus Tracks")
+			r, path, err := sf()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(r).ToNot(BeNil())
+			r.Close()
+			Expect(path).To(Equal(f1))
+		})
+
+		It("returns error when no matching file found", func() {
+			f1 := createFile("album/cover.jpg")
+			reader := &discArtworkReader{
+				discNumber: 1,
+				imgFiles:   []string{f1},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+			}
+
+			sf := reader.fromDiscSubtitle(ctx, "The Blue Disc")
+			_, _, err := sf()
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("matches first file when multiple extensions exist", func() {
+			f1 := createFile("album/The Blue Disc.jpg")
+			f2 := createFile("album/The Blue Disc.png")
+			reader := &discArtworkReader{
+				discNumber: 1,
+				imgFiles:   []string{f1, f2},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+			}
+
+			sf := reader.fromDiscSubtitle(ctx, "The Blue Disc")
+			r, path, err := sf()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(r).ToNot(BeNil())
+			r.Close()
+			Expect(path).To(Equal(f1))
+		})
+	})
+
+	Describe("discArtworkReader", func() {
+		Describe("fromDiscArtPriority", func() {
+			var (
+				reader *discArtworkReader
+				tmpDir string
+			)
+
+			BeforeEach(func() {
+				tmpDir = GinkgoT().TempDir()
+				reader = &discArtworkReader{
+					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",
+					},
+					firstTrackRel: "music/album/cd2/track1.flac",
+					lib:           libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
+				}
+			})
+
+			It("returns source funcs for glob patterns", func() {
+				ff := reader.fromDiscArtPriority(context.Background(), nil, "disc*.*")
+				Expect(ff).To(HaveLen(1))
+			})
+
+			It("returns source funcs for embedded pattern", func() {
+				ff := reader.fromDiscArtPriority(context.Background(), nil, "embedded")
+				Expect(ff).To(HaveLen(2)) // fromTag + fromFFmpegTag
+			})
+
+			It("handles multiple comma-separated patterns", func() {
+				ff := reader.fromDiscArtPriority(context.Background(), nil, "disc*.*, cd*.*, embedded")
+				Expect(ff).To(HaveLen(4)) // disc*.* + cd*.* + fromTag + fromFFmpegTag
+			})
+
+			It("ignores 'external' pattern silently", func() {
+				ff := reader.fromDiscArtPriority(context.Background(), nil, "external")
+				Expect(ff).To(HaveLen(0))
+			})
+
+			It("returns no source funcs when imgFiles is empty and pattern is not embedded", func() {
+				reader.imgFiles = nil
+				ff := reader.fromDiscArtPriority(context.Background(), nil, "disc*.*")
+				Expect(ff).To(HaveLen(0))
+			})
+
+			It("returns source func for discsubtitle pattern", func() {
+				reader.album = model.Album{Discs: model.Discs{2: "Bonus Tracks"}}
+				ff := reader.fromDiscArtPriority(context.Background(), nil, "discsubtitle")
+				Expect(ff).To(HaveLen(1))
+			})
+
+			It("returns no source func for discsubtitle when disc has no subtitle", func() {
+				reader.album = model.Album{Discs: model.Discs{2: ""}}
+				ff := reader.fromDiscArtPriority(context.Background(), nil, "discsubtitle")
+				Expect(ff).To(HaveLen(0))
+			})
+		})
+	})
+})
@@ -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) {
@@ -26,16 +27,27 @@ func newMediafileArtworkReader(ctx context.Context, artwork *artwork, artID mode
 	if err != nil {
 		return nil, err
 	}
+	_, _, imagesUpdatedAt, err := loadAlbumFoldersPaths(ctx, artwork.ds, *al)
+	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
-	if al.UpdatedAt.After(mf.UpdatedAt) {
+	a.cacheKey.lastUpdate = mf.UpdatedAt
+	if al.UpdatedAt.After(a.cacheKey.lastUpdate) {
 		a.cacheKey.lastUpdate = al.UpdatedAt
-	} else {
-		a.cacheKey.lastUpdate = mf.UpdatedAt
+	}
+	if imagesUpdatedAt != nil && imagesUpdatedAt.After(a.cacheKey.lastUpdate) {
+		a.cacheKey.lastUpdate = *imagesUpdatedAt
 	}
 	return a, nil
 }
@@ -54,12 +66,17 @@ 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)),
 		}
 	}
-	ff = append(ff, fromAlbum(ctx, a.a, a.mediafile.AlbumCoverArtID()))
+	// For multi-disc albums, fall back to disc artwork first; for single-disc albums,
+	// skip disc resolution (it would just fall through to album art anyway).
+	if len(a.album.Discs) > 1 {
+		ff = append(ff, fromAlbum(ctx, a.a, a.mediafile.DiscCoverArtID()))
+	} else {
+		ff = append(ff, fromAlbum(ctx, a.a, a.mediafile.AlbumCoverArtID()))
+	}
 	return selectImageReader(ctx, a.artID, ff...)
 }
@@ -8,12 +8,17 @@ import (
 	"image/draw"
 	"image/png"
 	"io"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
 	"time"

-	"github.com/disintegration/imaging"
+	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
+	xdraw "golang.org/x/image/draw"
 )

 type playlistArtworkReader struct {
@@ -35,6 +40,24 @@ func newPlaylistArtworkReader(ctx context.Context, artwork *artwork, artID model
 	}
 	a.cacheKey.artID = artID
 	a.cacheKey.lastUpdate = pl.UpdatedAt
+
+	// Check sidecar and ExternalImageURL local file ModTimes for cache invalidation.
+	// If either is newer than the playlist's UpdatedAt, use that instead so the
+	// cache is busted when a user replaces a sidecar image or local file reference.
+	for _, path := range []string{
+		findPlaylistSidecarPath(ctx, pl.Path),
+		pl.ExternalImageURL,
+	} {
+		if path == "" || strings.HasPrefix(path, "http://") || strings.HasPrefix(path, "https://") {
+			continue
+		}
+		if info, err := os.Stat(path); err == nil {
+			if info.ModTime().After(a.cacheKey.lastUpdate) {
+				a.cacheKey.lastUpdate = info.ModTime()
+			}
+		}
+	}
+
 	return a, nil
 }

@@ -43,11 +66,81 @@ func (a *playlistArtworkReader) LastUpdated() time.Time {
 }

 func (a *playlistArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
-	ff := []sourceFunc{
+	return selectImageReader(ctx, a.artID,
+		a.fromPlaylistUploadedImage(),
+		a.fromPlaylistSidecar(ctx),
+		a.fromPlaylistExternalImage(ctx),
 		a.fromGeneratedTiledCover(ctx),
 		fromAlbumPlaceholder(),
+	)
+}
+
+func (a *playlistArtworkReader) fromPlaylistUploadedImage() sourceFunc {
+	return fromLocalFile(a.pl.UploadedImagePath())
+}
+
+func (a *playlistArtworkReader) fromPlaylistSidecar(ctx context.Context) sourceFunc {
+	return fromLocalFile(findPlaylistSidecarPath(ctx, a.pl.Path))
+}
+
+func (a *playlistArtworkReader) fromPlaylistExternalImage(ctx context.Context) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		imgURL := a.pl.ExternalImageURL
+		if imgURL == "" {
+			return nil, "", nil
+		}
+		parsed, err := url.Parse(imgURL)
+		if err != nil {
+			return nil, "", err
+		}
+		if parsed.Scheme == "http" || parsed.Scheme == "https" {
+			if !conf.Server.EnableM3UExternalAlbumArt {
+				return nil, "", nil
+			}
+			return fromURL(ctx, parsed)
+		}
+		return fromLocalFile(imgURL)()
 	}
-	return selectImageReader(ctx, a.artID, ff...)
+}
+
+// fromLocalFile returns a sourceFunc that opens the given local path.
+// Returns (nil, "", nil) if path is empty — signalling "not found, try next source".
+func fromLocalFile(path string) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		if path == "" {
+			return nil, "", nil
+		}
+		f, err := os.Open(path)
+		if err != nil {
+			return nil, "", err
+		}
+		return f, path, nil
+	}
+}
+
+// findPlaylistSidecarPath scans the directory of the playlist file for a sidecar
+// image file with the same base name (case-insensitive). Returns empty string if
+// no matching image is found or if plsPath is empty.
+func findPlaylistSidecarPath(ctx context.Context, plsPath string) string {
+	if plsPath == "" {
+		return ""
+	}
+	dir := filepath.Dir(plsPath)
+	base := strings.TrimSuffix(filepath.Base(plsPath), filepath.Ext(plsPath))
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		log.Warn(ctx, "Could not read directory for playlist sidecar", "dir", dir, err)
+		return ""
+	}
+	for _, entry := range entries {
+		name := entry.Name()
+		nameBase := strings.TrimSuffix(name, filepath.Ext(name))
+		if !entry.IsDir() && strings.EqualFold(nameBase, base) && model.IsImageFile(name) {
+			return filepath.Join(dir, name)
+		}
+	}
+	return ""
 }

 func (a *playlistArtworkReader) fromGeneratedTiledCover(ctx context.Context) sourceFunc {
@@ -107,7 +200,7 @@ func (a *playlistArtworkReader) createTile(_ context.Context, r io.ReadCloser) (
 	if err != nil {
 		return nil, err
 	}
-	return imaging.Fill(img, tileSize/2, tileSize/2, imaging.Center, imaging.Lanczos), nil
+	return fillCenter(img, tileSize/2, tileSize/2), nil
 }

 func (a *playlistArtworkReader) createTiledImage(_ context.Context, tiles []image.Image) (io.ReadCloser, error) {
@@ -145,3 +238,32 @@ func rect(pos int) image.Rectangle {
 	r.Max.Y = r.Min.Y + tileSize/2
 	return r
 }
+
+// fillCenter crops the source image from the center and scales it to fill dstW x dstH exactly,
+// equivalent to imaging.Fill with Center anchor.
+func fillCenter(src image.Image, dstW, dstH int) image.Image {
+	srcBounds := src.Bounds()
+	srcW := srcBounds.Dx()
+	srcH := srcBounds.Dy()
+
+	// Calculate crop rectangle (center crop to match destination aspect ratio)
+	srcAspect := float64(srcW) / float64(srcH)
+	dstAspect := float64(dstW) / float64(dstH)
+
+	var cropRect image.Rectangle
+	if srcAspect > dstAspect {
+		// Source is wider — crop horizontally
+		cropW := int(float64(srcH) * dstAspect)
+		cropX := (srcW - cropW) / 2
+		cropRect = image.Rect(srcBounds.Min.X+cropX, srcBounds.Min.Y, srcBounds.Min.X+cropX+cropW, srcBounds.Max.Y)
+	} else {
+		// Source is taller — crop vertically
+		cropH := int(float64(srcW) / dstAspect)
+		cropY := (srcH - cropH) / 2
+		cropRect = image.Rect(srcBounds.Min.X, srcBounds.Min.Y+cropY, srcBounds.Max.X, srcBounds.Min.Y+cropY+cropH)
+	}
+
+	dst := image.NewNRGBA(image.Rect(0, 0, dstW, dstH))
+	xdraw.CatmullRom.Scale(dst, dst.Bounds(), src, cropRect, draw.Src, nil)
+	return dst
+}
@@ -0,0 +1,40 @@
+package artwork
+
+import (
+	"context"
+	"io"
+	"time"
+
+	"github.com/navidrome/navidrome/model"
+)
+
+type radioArtworkReader struct {
+	cacheKey
+	a     *artwork
+	radio model.Radio
+}
+
+func newRadioArtworkReader(ctx context.Context, artwork *artwork, artID model.ArtworkID) (*radioArtworkReader, error) {
+	r, err := artwork.ds.Radio(ctx).Get(artID.ID)
+	if err != nil {
+		return nil, err
+	}
+	a := &radioArtworkReader{a: artwork, radio: *r}
+	a.cacheKey.artID = artID
+	a.cacheKey.lastUpdate = r.UpdatedAt
+	return a, nil
+}
+
+func (a *radioArtworkReader) LastUpdated() time.Time {
+	return a.lastUpdate
+}
+
+func (a *radioArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
+	return selectImageReader(ctx, a.artID,
+		a.fromRadioUploadedImage(),
+	)
+}
+
+func (a *radioArtworkReader) fromRadioUploadedImage() sourceFunc {
+	return fromLocalFile(a.radio.UploadedImagePath())
+}
@@ -0,0 +1,84 @@
+package artwork
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("radioArtworkReader", func() {
+	var (
+		tempDir string
+		reader  *radioArtworkReader
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		tempDir = GinkgoT().TempDir()
+		conf.Server.DataFolder = tempDir
+
+		Expect(os.MkdirAll(filepath.Join(tempDir, "artwork", "radio"), 0755)).To(Succeed())
+
+		reader = &radioArtworkReader{}
+	})
+
+	Describe("fromRadioUploadedImage", func() {
+		When("radio has an uploaded image", func() {
+			It("returns the uploaded image", func() {
+				imgPath := filepath.Join(tempDir, "artwork", "radio", "rd-1_test.jpg")
+				Expect(os.WriteFile(imgPath, []byte("uploaded radio image"), 0600)).To(Succeed())
+
+				reader.radio = model.Radio{ID: "rd-1", UploadedImage: "rd-1_test.jpg"}
+				sf := reader.fromRadioUploadedImage()
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				Expect(path).To(Equal(imgPath))
+				r.Close()
+			})
+		})
+
+		When("radio has no uploaded image", func() {
+			It("returns nil reader (falls through)", func() {
+				reader.radio = model.Radio{ID: "rd-1"}
+				sf := reader.fromRadioUploadedImage()
+				r, path, err := sf()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).To(BeNil())
+				Expect(path).To(BeEmpty())
+			})
+		})
+	})
+
+	Describe("Reader", func() {
+		When("radio has an uploaded image", func() {
+			It("returns the image reader", func() {
+				imgPath := filepath.Join(tempDir, "artwork", "radio", "rd-1_test.jpg")
+				Expect(os.WriteFile(imgPath, []byte("uploaded radio image"), 0600)).To(Succeed())
+
+				reader.radio = model.Radio{ID: "rd-1", UploadedImage: "rd-1_test.jpg"}
+				reader.cacheKey.artID = model.ArtworkID{Kind: model.KindRadioArtwork, ID: "rd-1"}
+				r, _, err := reader.Reader(context.Background())
+				Expect(err).ToNot(HaveOccurred())
+				Expect(r).ToNot(BeNil())
+				r.Close()
+			})
+		})
+
+		When("radio has no uploaded image", func() {
+			It("returns ErrUnavailable", func() {
+				reader.radio = model.Radio{ID: "rd-1"}
+				reader.cacheKey.artID = model.ArtworkID{Kind: model.KindRadioArtwork, ID: "rd-1"}
+				r, _, err := reader.Reader(context.Background())
+				Expect(err).To(MatchError(ErrUnavailable))
+				Expect(r).To(BeNil())
+			})
+		})
+	})
+})
@@ -5,17 +5,36 @@ import (
 	"context"
 	"fmt"
 	"image"
+	"image/draw"
 	"image/jpeg"
 	"image/png"
 	"io"
+	"sync"
 	"time"

-	"github.com/disintegration/imaging"
+	"github.com/gen2brain/webp"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	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)
+	},
+}
+
 type resizedArtworkReader struct {
 	artID      model.ArtworkID
 	cacheKey   string
@@ -46,7 +65,7 @@ func (a *resizedArtworkReader) Key() string {
 	if a.square {
 		return baseKey + ".square"
 	}
-	return fmt.Sprintf("%s.%d", baseKey, conf.Server.CoverJpegQuality)
+	return fmt.Sprintf("%s.%d", baseKey, conf.Server.CoverArtQuality)
 }

 func (a *resizedArtworkReader) LastUpdated() time.Time {
@@ -61,7 +80,7 @@ func (a *resizedArtworkReader) Reader(ctx context.Context) (io.ReadCloser, strin
 	}
 	defer orig.Close()

-	resized, origSize, err := resizeImage(orig, a.size, a.square)
+	resized, origSize, err := a.resizeImage(ctx, orig)
 	if resized == nil {
 		log.Trace(ctx, "Image smaller than requested size", "artID", a.artID, "original", origSize, "resized", a.size, "square", a.square)
 	} else {
@@ -75,11 +94,40 @@ func (a *resizedArtworkReader) Reader(ctx context.Context) (io.ReadCloser, strin
 		orig, _, err = a.a.Get(ctx, a.artID, 0, false)
 		return orig, "", err
 	}
+	// Preserve ReadCloser semantics if the resized reader already supports Close
+	// (e.g., ffmpeg pipe), otherwise wrap with NopCloser
+	if rc, ok := resized.(io.ReadCloser); ok {
+		return rc, fmt.Sprintf("%s@%d", a.artID, a.size), nil
+	}
 	return io.NopCloser(resized), fmt.Sprintf("%s@%d", a.artID, a.size), nil
 }

-func resizeImage(reader io.Reader, size int, square bool) (io.Reader, int, error) {
-	original, format, err := image.Decode(reader)
+func (a *resizedArtworkReader) resizeImage(ctx context.Context, reader io.Reader) (io.Reader, int, error) {
+	data, err := io.ReadAll(reader)
+	if err != nil {
+		return nil, 0, fmt.Errorf("reading image data: %w", err)
+	}
+
+	// Preserve animation for animated images
+	if isAnimatedGIF(data) {
+		if a.a.ffmpeg.IsAvailable() {
+			// Animated GIF: convert to animated WebP via ffmpeg (with optional resize)
+			r, err := a.a.ffmpeg.ConvertAnimatedImage(ctx, bytes.NewReader(data), a.size, conf.Server.CoverArtQuality)
+			if err == nil {
+				return r, 0, nil
+			}
+			log.Warn(ctx, "Could not convert animated GIF, falling back to static", err)
+		}
+	} else if isAnimatedWebP(data) || isAnimatedPNG(data) {
+		// Animated WebP/APNG: return original as-is (ffmpeg can't re-encode these)
+		return bytes.NewReader(data), 0, nil
+	}
+
+	return resizeStaticImage(data, a.size, a.square)
+}
+
+func resizeStaticImage(data []byte, size int, square bool) (io.Reader, int, error) {
+	original, format, err := image.Decode(bytes.NewReader(data))
 	if err != nil {
 		return nil, 0, err
 	}
@@ -96,26 +144,43 @@ func resizeImage(reader io.Reader, size int, square bool) (io.Reader, int, error
 		return nil, originalSize, nil
 	}

-	var resized image.Image
-	if originalSize >= size {
-		resized = imaging.Fit(original, size, size, imaging.Lanczos)
-	} else {
-		if bounds.Max.Y < bounds.Max.X {
-			resized = imaging.Resize(original, size, 0, imaging.Lanczos)
-		} else {
-			resized = imaging.Resize(original, 0, size, imaging.Lanczos)
-		}
-	}
-	if square {
-		bg := image.NewRGBA(image.Rect(0, 0, size, size))
-		resized = imaging.OverlayCenter(bg, resized, 1)
-	}
+	// Calculate aspect-fit dimensions
+	srcW, srcH := bounds.Dx(), bounds.Dy()
+	scale := float64(size) / float64(max(srcW, srcH))
+	dstW := int(float64(srcW) * scale)
+	dstH := int(float64(srcH) * scale)

-	buf := new(bytes.Buffer)
-	if format == "png" || square {
-		err = png.Encode(buf, resized)
+	var dst *image.NRGBA
+	var dstRect image.Rectangle
+	if square {
+		// Square canvas with image centered (transparent padding via zero-initialized NRGBA)
+		dst = image.NewNRGBA(image.Rect(0, 0, size, size))
+		offsetX := (size - dstW) / 2
+		offsetY := (size - dstH) / 2
+		dstRect = image.Rect(offsetX, offsetY, offsetX+dstW, offsetY+dstH)
 	} else {
-		err = jpeg.Encode(buf, resized, &jpeg.Options{Quality: conf.Server.CoverJpegQuality})
+		// Tight-fit canvas
+		dst = image.NewNRGBA(image.Rect(0, 0, dstW, dstH))
+		dstRect = dst.Bounds()
 	}
-	return buf, originalSize, err
+	xdraw.CatmullRom.Scale(dst, dstRect, original, bounds, draw.Src, nil)
+
+	buf := bufPool.Get().(*bytes.Buffer)
+	buf.Reset()
+	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)
+		return nil, originalSize, err
+	}
+	// Copy bytes before returning buffer to pool (pool may reuse the buffer)
+	encoded := make([]byte, buf.Len())
+	copy(encoded, buf.Bytes())
+	bufPool.Put(buf)
+	return bytes.NewReader(encoded), originalSize, nil
 }
@@ -0,0 +1,176 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+
+	"github.com/navidrome/navidrome/core/ffmpeg"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("resizeImage", func() {
+	var mockFF *tests.MockFFmpeg
+	var r *resizedArtworkReader
+
+	BeforeEach(func() {
+		mockFF = tests.NewMockFFmpeg("converted-animated-data")
+		r = &resizedArtworkReader{
+			size:   300,
+			square: false,
+			a:      &artwork{ffmpeg: mockFF},
+		}
+	})
+
+	Describe("animated GIF handling", func() {
+		It("converts animated GIF via ffmpeg when available", func() {
+			data := createAnimatedGIF(3)
+			result, _, err := r.resizeImage(context.Background(), bytes.NewReader(data))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).ToNot(BeNil())
+
+			// Should have been processed by ffmpeg (mock returns "converted-animated-data")
+			output, err := io.ReadAll(result)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output).To(Equal(data)) // MockFFmpeg echoes input back
+		})
+
+		It("falls back to static resize when ffmpeg fails for animated GIF", func() {
+			mockFF.Error = errors.New("ffmpeg failed")
+			// Use size smaller than image so static resize actually produces output
+			r.size = 1
+			data := createAnimatedGIF(3)
+			result, _, err := r.resizeImage(context.Background(), bytes.NewReader(data))
+			// Should fall through to static resize successfully (no ffmpeg error propagated)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).ToNot(BeNil())
+
+			// Verify it's a static image (WebP encoded), not the ffmpeg error
+			output, err := io.ReadAll(result)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(len(output)).To(BeNumerically(">", 0))
+		})
+
+		It("preserves animation for square thumbnails with animated GIF", func() {
+			r.square = true
+			data := createAnimatedGIF(3)
+			result, _, err := r.resizeImage(context.Background(), bytes.NewReader(data))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).ToNot(BeNil())
+
+			// Should have been processed by ffmpeg (mock returns input data)
+			output, err := io.ReadAll(result)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output).To(Equal(data))
+		})
+	})
+
+	Describe("animated WebP handling", func() {
+		It("returns animated WebP data as-is when not square", func() {
+			data := createAnimatedWebPBytes()
+			result, _, err := r.resizeImage(context.Background(), bytes.NewReader(data))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).ToNot(BeNil())
+
+			// Should return original data unchanged
+			output, err := io.ReadAll(result)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output).To(Equal(data))
+		})
+
+		It("preserves animated WebP for square thumbnails", func() {
+			r.square = true
+			data := createAnimatedWebPBytes()
+			result, _, err := r.resizeImage(context.Background(), bytes.NewReader(data))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).ToNot(BeNil())
+
+			// Should return original data unchanged
+			output, err := io.ReadAll(result)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output).To(Equal(data))
+		})
+	})
+
+	Describe("animated PNG handling", func() {
+		It("returns animated PNG data as-is when not square", func() {
+			data := createAPNGBytes()
+			result, _, err := r.resizeImage(context.Background(), bytes.NewReader(data))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).ToNot(BeNil())
+
+			// Should return original data unchanged
+			output, err := io.ReadAll(result)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output).To(Equal(data))
+		})
+
+		It("preserves animated PNG for square thumbnails", func() {
+			r.square = true
+			data := createAPNGBytes()
+			result, _, err := r.resizeImage(context.Background(), bytes.NewReader(data))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).ToNot(BeNil())
+
+			// Should return original data unchanged
+			output, err := io.ReadAll(result)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output).To(Equal(data))
+		})
+	})
+
+	Describe("static image handling", func() {
+		It("resizes a static PNG normally", func() {
+			data := createStaticPNGBytes()
+			result, _, err := r.resizeImage(context.Background(), bytes.NewReader(data))
+			// Static PNG is 2x2, size 300 is larger, so should return nil (no upscale)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(BeNil())
+		})
+	})
+
+	Describe("ReadCloser preservation", func() {
+		It("preserves Close semantics from ffmpeg ReadCloser", func() {
+			// Create a trackable ReadCloser
+			tracker := &closeTracker{Reader: bytes.NewReader([]byte("test data"))}
+			mockFF2 := &mockFFmpegWithCloser{tracker: tracker}
+			r.a = &artwork{ffmpeg: mockFF2}
+
+			data := createAnimatedGIF(3)
+			result, _, err := r.resizeImage(context.Background(), bytes.NewReader(data))
+			Expect(err).ToNot(HaveOccurred())
+
+			// The result should be an io.ReadCloser (the tracker)
+			rc, ok := result.(io.ReadCloser)
+			Expect(ok).To(BeTrue())
+			Expect(rc.Close()).ToNot(HaveOccurred())
+			Expect(tracker.closed).To(BeTrue())
+		})
+	})
+})
+
+// closeTracker is an io.ReadCloser that tracks whether Close was called.
+type closeTracker struct {
+	io.Reader
+	closed bool
+}
+
+func (c *closeTracker) Close() error {
+	c.closed = true
+	return nil
+}
+
+// mockFFmpegWithCloser is a minimal FFmpeg mock that returns a specific ReadCloser
+// for ConvertAnimatedImage, allowing us to verify Close propagation.
+type mockFFmpegWithCloser struct {
+	ffmpeg.FFmpeg
+	tracker *closeTracker
+}
+
+func (m *mockFFmpegWithCloser) IsAvailable() bool { return true }
+func (m *mockFFmpegWithCloser) ConvertAnimatedImage(_ context.Context, _ io.Reader, _ int, _ int) (io.ReadCloser, error) {
+	return m.tracker, nil
+}
@@ -5,9 +5,9 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"io/fs"
 	"net/http"
 	"net/url"
-	"os"
 	"path/filepath"
 	"reflect"
 	"regexp"
@@ -15,8 +15,6 @@ import (
 	"strings"
 	"time"

-	"github.com/dhowden/tag"
-	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/core/ffmpeg"
@@ -55,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)
@@ -67,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)
 	}
@@ -85,80 +83,43 @@ var picTypeRegexes = []*regexp.Regexp{
 	regexp.MustCompile(`(?i).*cover.*`),
 }

-func fromTag(ctx context.Context, path string) sourceFunc {
-	if conf.Server.DevLegacyEmbedImage {
-		return fromTagLegacy(ctx, path)
-	}
-	return fromTagGoTaglib(ctx, path)
-}
-
-func fromTagLegacy(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 := os.Open(path)
+		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()

-		m, err := tag.ReadFrom(f)
-		if err != nil {
-			return nil, "", err
-		}
-
-		types := m.PictureTypes()
-		if len(types) == 0 {
-			return nil, "", fmt.Errorf("no embedded image found in %s", path)
-		}
-
-		var picture *tag.Picture
-		for _, regex := range picTypeRegexes {
-			for _, t := range types {
-				if regex.MatchString(t) {
-					log.Trace(ctx, "Found embedded image", "type", t, "path", path)
-					picture = m.Pictures(t)
-					break
-				}
-			}
-			if picture != nil {
-				break
-			}
-		}
-		if picture == nil {
-			log.Trace(ctx, "Could not find a front image. Getting the first one", "type", types[0], "path", path)
-			picture = m.Picture()
-		}
-		if picture == nil {
-			return nil, "", fmt.Errorf("could not load embedded image from %s", path)
-		}
-		return io.NopCloser(bytes.NewReader(picture.Data)), path, nil
-	}
-}
-
-func fromTagGoTaglib(ctx context.Context, path string) sourceFunc {
-	return func() (io.ReadCloser, string, error) {
-		if path == "" {
-			return nil, "", nil
-		}
-		f, err := taglib.OpenReadOnly(path, taglib.WithReadStyle(taglib.ReadStyleFast))
-		if err != nil {
-			return nil, "", err
-		}
-		defer f.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
 	}
 }

@@ -175,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 == "" {
@@ -184,10 +152,25 @@ func fromFFmpegTag(ctx context.Context, ffmpeg ffmpeg.FFmpeg, path string) sourc
 		if err != nil {
 			return nil, "", err
 		}
-		return r, path, nil
+		// Validate that the stream actually contains image data by reading the first byte.
+		// ffmpeg.ExtractImage returns a pipe reader that may fail asynchronously if the
+		// file has no video/image stream (e.g., an MP3 without embedded art).
+		buf := make([]byte, 1)
+		n, err := r.Read(buf)
+		if n == 0 || err != nil {
+			r.Close()
+			return nil, "", fmt.Errorf("ffmpeg produced no image data for %s: %w", path, err)
+		}
+		return readCloser{Reader: io.MultiReader(bytes.NewReader(buf[:n]), r), Closer: r}, path, nil
 	}
 }

+// readCloser combines a Reader and a Closer into an io.ReadCloser.
+type readCloser struct {
+	io.Reader
+	io.Closer
+}
+
 func fromAlbum(ctx context.Context, a *artwork, id model.ArtworkID) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
 		r, _, err := a.Get(ctx, id, 0, false)
@@ -230,7 +213,7 @@ func fromURL(ctx context.Context, imageUrl *url.URL) (io.ReadCloser, string, err
 	hc := http.Client{Timeout: 5 * time.Second}
 	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, imageUrl.String(), nil)
 	req.Header.Set("User-Agent", consts.HTTPUserAgent)
-	resp, err := hc.Do(req)
+	resp, err := hc.Do(req) //nolint:gosec
 	if err != nil {
 		return nil, "", err
 	}
@@ -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") }
@@ -4,12 +4,11 @@ import (
 	"cmp"
 	"context"
 	"crypto/sha256"
-	"maps"
 	"sync"
 	"time"

 	"github.com/go-chi/jwtauth/v5"
-	"github.com/lestrrat-go/jwx/v2/jwt"
+	"github.com/lestrrat-go/jwx/v3/jwt"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
@@ -46,38 +45,30 @@ func Init(ds model.DataStore) {
 	})
 }

-func createBaseClaims() map[string]any {
-	tokenClaims := map[string]any{}
-	tokenClaims[jwt.IssuerKey] = consts.JWTIssuer
-	return tokenClaims
-}
-
-func CreatePublicToken(claims map[string]any) (string, error) {
-	tokenClaims := createBaseClaims()
-	maps.Copy(tokenClaims, claims)
-	_, token, err := TokenAuth.Encode(tokenClaims)
-
+func CreatePublicToken(claims Claims) (string, error) {
+	claims.Issuer = consts.JWTIssuer
+	_, token, err := TokenAuth.Encode(claims.ToMap())
 	return token, err
 }

-func CreateExpiringPublicToken(exp time.Time, claims map[string]any) (string, error) {
-	tokenClaims := createBaseClaims()
+func CreateExpiringPublicToken(exp time.Time, claims Claims) (string, error) {
+	claims.Issuer = consts.JWTIssuer
 	if !exp.IsZero() {
-		tokenClaims[jwt.ExpirationKey] = exp.UTC().Unix()
+		claims.ExpiresAt = exp
 	}
-	maps.Copy(tokenClaims, claims)
-	_, token, err := TokenAuth.Encode(tokenClaims)
-
+	_, token, err := TokenAuth.Encode(claims.ToMap())
 	return token, err
 }

 func CreateToken(u *model.User) (string, error) {
-	claims := createBaseClaims()
-	claims[jwt.SubjectKey] = u.UserName
-	claims[jwt.IssuedAtKey] = time.Now().UTC().Unix()
-	claims["uid"] = u.ID
-	claims["adm"] = u.IsAdmin
-	token, _, err := TokenAuth.Encode(claims)
+	claims := Claims{
+		Issuer:   consts.JWTIssuer,
+		Subject:  u.UserName,
+		IssuedAt: time.Now(),
+		UserID:   u.ID,
+		IsAdmin:  u.IsAdmin,
+	}
+	token, _, err := TokenAuth.Encode(claims.ToMap())
 	if err != nil {
 		return "", err
 	}
@@ -86,23 +77,18 @@ func CreateToken(u *model.User) (string, error) {
 }

 func TouchToken(token jwt.Token) (string, error) {
-	claims, err := token.AsMap(context.Background())
-	if err != nil {
-		return "", err
-	}
-
-	claims[jwt.ExpirationKey] = time.Now().UTC().Add(conf.Server.SessionTimeout).Unix()
-	_, newToken, err := TokenAuth.Encode(claims)
-
+	claims := ClaimsFromToken(token).
+		WithExpiresAt(time.Now().UTC().Add(conf.Server.SessionTimeout))
+	_, newToken, err := TokenAuth.Encode(claims.ToMap())
 	return newToken, err
 }

-func Validate(tokenStr string) (map[string]any, error) {
+func Validate(tokenStr string) (Claims, error) {
 	token, err := jwtauth.VerifyToken(TokenAuth, tokenStr)
 	if err != nil {
-		return nil, err
+		return Claims{}, err
 	}
-	return token.AsMap(context.Background())
+	return ClaimsFromToken(token), nil
 }

 func WithAdminUser(ctx context.Context, ds model.DataStore) context.Context {
@@ -134,6 +120,19 @@ func createNewSecret(ctx context.Context, ds model.DataStore) string {
 	return secret
 }

+// EncodeToken creates a signed JWT from an arbitrary claims map.
+// It sets the issuer claim automatically.
+func EncodeToken(claims map[string]any) (string, error) {
+	claims[jwt.IssuerKey] = consts.JWTIssuer
+	_, token, err := TokenAuth.Encode(claims)
+	return token, err
+}
+
+// DecodeAndVerifyToken verifies a JWT string and returns the parsed token.
+func DecodeAndVerifyToken(tokenStr string) (jwt.Token, error) {
+	return jwtauth.VerifyToken(TokenAuth, tokenStr)
+}
+
 func getEncKey() []byte {
 	key := cmp.Or(
 		conf.Server.PasswordEncryptionKey,
@@ -54,7 +54,7 @@ var _ = Describe("Auth", func() {

 			decodedClaims, err := auth.Validate(tokenStr)
 			Expect(err).NotTo(HaveOccurred())
-			Expect(decodedClaims["iss"]).To(Equal("issuer"))
+			Expect(decodedClaims.Issuer).To(Equal("issuer"))
 		})

 		It("returns ErrExpired if the `exp` field is in the past", func() {
@@ -82,11 +82,11 @@ var _ = Describe("Auth", func() {
 			claims, err := auth.Validate(tokenStr)
 			Expect(err).NotTo(HaveOccurred())

-			Expect(claims["iss"]).To(Equal(consts.JWTIssuer))
-			Expect(claims["sub"]).To(Equal("johndoe"))
-			Expect(claims["uid"]).To(Equal("123"))
-			Expect(claims["adm"]).To(Equal(true))
-			Expect(claims["exp"]).To(BeTemporally(">", time.Now()))
+			Expect(claims.Issuer).To(Equal(consts.JWTIssuer))
+			Expect(claims.Subject).To(Equal("johndoe"))
+			Expect(claims.UserID).To(Equal("123"))
+			Expect(claims.IsAdmin).To(Equal(true))
+			Expect(claims.ExpiresAt).To(BeTemporally(">", time.Now()))
 		})
 	})

@@ -104,8 +104,7 @@ var _ = Describe("Auth", func() {

 			decodedClaims, err := auth.Validate(touched)
 			Expect(err).NotTo(HaveOccurred())
-			exp := decodedClaims["exp"].(time.Time)
-			Expect(exp.Sub(yesterday)).To(BeNumerically(">=", oneDay))
+			Expect(decodedClaims.ExpiresAt.Sub(yesterday)).To(BeNumerically(">=", oneDay))
 		})
 	})
 })
@@ -0,0 +1,104 @@
+package auth
+
+import (
+	"time"
+
+	"github.com/lestrrat-go/jwx/v3/jwt"
+)
+
+// Claims represents the typed JWT claims used throughout Navidrome,
+// replacing the untyped map[string]any approach.
+type Claims struct {
+	// Standard JWT claims
+	Issuer    string
+	Subject   string // username for session tokens
+	IssuedAt  time.Time
+	ExpiresAt time.Time
+
+	// Custom claims
+	UserID  string // "uid"
+	IsAdmin bool   // "adm"
+	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().
+// Only non-zero fields are included.
+func (c Claims) ToMap() map[string]any {
+	m := make(map[string]any)
+	if c.Issuer != "" {
+		m[jwt.IssuerKey] = c.Issuer
+	}
+	if c.Subject != "" {
+		m[jwt.SubjectKey] = c.Subject
+	}
+	if !c.IssuedAt.IsZero() {
+		m[jwt.IssuedAtKey] = c.IssuedAt.UTC().Unix()
+	}
+	if !c.ExpiresAt.IsZero() {
+		m[jwt.ExpirationKey] = c.ExpiresAt.UTC().Unix()
+	}
+	if c.UserID != "" {
+		m["uid"] = c.UserID
+	}
+	if c.IsAdmin {
+		m["adm"] = c.IsAdmin
+	}
+	if c.ID != "" {
+		m["id"] = c.ID
+	}
+	if c.Format != "" {
+		m["f"] = c.Format
+	}
+	if c.BitRate != 0 {
+		m["b"] = c.BitRate
+	}
+	if c.ShareID != "" {
+		m["sid"] = c.ShareID
+	}
+	return m
+}
+
+func (c Claims) WithExpiresAt(t time.Time) Claims {
+	c.ExpiresAt = t
+	return c
+}
+
+// ClaimsFromToken extracts Claims directly from a jwt.Token using token.Get().
+func ClaimsFromToken(token jwt.Token) Claims {
+	var c Claims
+	c.Issuer, _ = token.Issuer()
+	c.Subject, _ = token.Subject()
+	c.IssuedAt, _ = token.IssuedAt()
+	c.ExpiresAt, _ = token.Expiration()
+
+	var uid string
+	if err := token.Get("uid", &uid); err == nil {
+		c.UserID = uid
+	}
+	var adm bool
+	if err := token.Get("adm", &adm); err == nil {
+		c.IsAdmin = adm
+	}
+	var id string
+	if err := token.Get("id", &id); err == nil {
+		c.ID = id
+	}
+	var f string
+	if err := token.Get("f", &f); err == nil {
+		c.Format = f
+	}
+	if err := token.Get("b", &c.BitRate); err != nil {
+		var bf float64
+		if err := token.Get("b", &bf); err == nil {
+			c.BitRate = int(bf)
+		}
+	}
+	var sid string
+	if err := token.Get("sid", &sid); err == nil {
+		c.ShareID = sid
+	}
+	return c
+}
@@ -0,0 +1,108 @@
+package auth_test
+
+import (
+	"time"
+
+	"github.com/go-chi/jwtauth/v5"
+	"github.com/navidrome/navidrome/core/auth"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Claims", func() {
+	Describe("ToMap", func() {
+		It("includes only non-zero fields", func() {
+			c := auth.Claims{
+				Issuer:  "ND",
+				Subject: "johndoe",
+				UserID:  "123",
+				IsAdmin: true,
+			}
+			m := c.ToMap()
+			Expect(m).To(HaveKeyWithValue("iss", "ND"))
+			Expect(m).To(HaveKeyWithValue("sub", "johndoe"))
+			Expect(m).To(HaveKeyWithValue("uid", "123"))
+			Expect(m).To(HaveKeyWithValue("adm", true))
+			Expect(m).NotTo(HaveKey("exp"))
+			Expect(m).NotTo(HaveKey("iat"))
+			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() {
+			now := time.Now()
+			c := auth.Claims{
+				IssuedAt:  now,
+				ExpiresAt: now.Add(time.Hour),
+			}
+			m := c.ToMap()
+			Expect(m).To(HaveKey("iat"))
+			Expect(m).To(HaveKey("exp"))
+		})
+
+		It("includes custom claims for public tokens", func() {
+			c := auth.Claims{
+				ID:      "al-123",
+				Format:  "mp3",
+				BitRate: 192,
+			}
+			m := c.ToMap()
+			Expect(m).To(HaveKeyWithValue("id", "al-123"))
+			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() {
+		It("round-trips session claims through encode/decode", func() {
+			tokenAuth := jwtauth.New("HS256", []byte("test-secret"), nil)
+			now := time.Now().Truncate(time.Second)
+			original := auth.Claims{
+				Issuer:  "ND",
+				Subject: "johndoe",
+				UserID:  "123",
+				IsAdmin: true,
+			}
+			m := original.ToMap()
+			m["iat"] = now.UTC().Unix()
+			token, _, err := tokenAuth.Encode(m)
+			Expect(err).NotTo(HaveOccurred())
+
+			c := auth.ClaimsFromToken(token)
+			Expect(c.Issuer).To(Equal("ND"))
+			Expect(c.Subject).To(Equal("johndoe"))
+			Expect(c.UserID).To(Equal("123"))
+			Expect(c.IsAdmin).To(BeTrue())
+			Expect(c.IssuedAt.UTC()).To(Equal(now.UTC()))
+		})
+
+		It("round-trips public token claims through encode/decode", func() {
+			tokenAuth := jwtauth.New("HS256", []byte("test-secret"), nil)
+			original := auth.Claims{
+				Issuer:  "ND",
+				ID:      "al-456",
+				Format:  "opus",
+				BitRate: 128,
+				ShareID: "abc1234567",
+			}
+			token, _, err := tokenAuth.Encode(original.ToMap())
+			Expect(err).NotTo(HaveOccurred())
+
+			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))
+		})
+	})
+
+})
@@ -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"))
@@ -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
@@ -374,13 +376,25 @@ func (e *provider) ArtistImage(ctx context.Context, id string) (*url.URL, error)
 		return nil, err
 	}

-	e.callGetImage(ctx, e.ag, &artist)
-	if utils.IsCtxDone(ctx) {
-		log.Warn(ctx, "ArtistImage call canceled", ctx.Err())
-		return nil, ctx.Err()
+	imageUrl := artist.ArtistImageUrl()
+	if imageUrl == "" {
+		// No cached URL — must fetch from external source synchronously
+		e.callGetImage(ctx, e.ag, &artist)
+		if utils.IsCtxDone(ctx) {
+			log.Warn(ctx, "ArtistImage call canceled", ctx.Err())
+			return nil, ctx.Err()
+		}
+		imageUrl = artist.ArtistImageUrl()
+	} else {
+		// If cached info is expired, enqueue a background refresh so that config changes
+		// (e.g. disabling an agent) take effect without waiting for a full artist info refresh.
+		updatedAt := V(artist.ExternalInfoUpdatedAt)
+		if !updatedAt.IsZero() && time.Since(updatedAt) > conf.Server.DevArtistInfoTimeToLive {
+			log.Debug(ctx, "Artist image info expired, enqueuing background refresh", "artist", artist.Name(), "updatedAt", updatedAt)
+			e.artistQueue.enqueue(&artist)
+		}
 	}

-	imageUrl := artist.ArtistImageUrl()
 	if imageUrl == "" {
 		return nil, model.ErrNotFound
 	}
@@ -467,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
 	}
@@ -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)
@@ -1,14 +1,18 @@
 package external_test

 import (
+	"bytes"
 	"context"
 	"errors"
 	"net/url"
+	"time"

 	"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/core/matcher"
+	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -48,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()
@@ -266,6 +270,68 @@ var _ = Describe("Provider - ArtistImage", func() {
 		mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-1", "Artist One", "")
 	})

+	It("returns cached URL and does not call agent when info is not expired", func() {
+		// Arrange: artist has a cached image URL with recent ExternalInfoUpdatedAt
+		recentTime := time.Now().Add(-1 * time.Minute)
+		cachedArtist := &model.Artist{
+			ID:                    "artist-cached",
+			Name:                  "Cached Artist",
+			LargeImageUrl:         "http://example.com/cached-large.jpg",
+			ExternalInfoUpdatedAt: &recentTime,
+		}
+		mockArtistRepo.On("Get", "artist-cached").Return(cachedArtist, nil).Maybe()
+		expectedURL, _ := url.Parse("http://example.com/cached-large.jpg")
+
+		// Capture log output
+		var logBuf bytes.Buffer
+		log.SetOutput(&logBuf)
+		defer log.SetOutput(GinkgoWriter)
+		log.SetLevel(log.LevelDebug)
+
+		// Act
+		imgURL, err := provider.ArtistImage(ctx, "artist-cached")
+
+		// Assert
+		Expect(err).ToNot(HaveOccurred())
+		Expect(imgURL).To(Equal(expectedURL))
+		mockImageAgent.AssertNotCalled(GinkgoT(), "GetArtistImages", mock.Anything, "artist-cached", mock.Anything, mock.Anything)
+
+		// Assert: background refresh was NOT enqueued
+		Expect(logBuf.String()).ToNot(ContainSubstring("Artist image info expired, enqueuing background refresh"))
+
+	})
+
+	It("returns stale URL and enqueues refresh when info is expired", func() {
+		// Arrange
+		conf.Server.DevArtistInfoTimeToLive = 1 * time.Nanosecond
+		expiredTime := time.Now().Add(-1 * time.Hour)
+		staleArtist := &model.Artist{
+			ID:                    "artist-expired",
+			Name:                  "Expired Artist",
+			LargeImageUrl:         "http://example.com/expired-large.jpg",
+			ExternalInfoUpdatedAt: &expiredTime,
+		}
+		mockArtistRepo.On("Get", "artist-expired").Return(staleArtist, nil).Maybe()
+		expectedURL, _ := url.Parse("http://example.com/expired-large.jpg")
+
+		// Capture log output
+		var logBuf bytes.Buffer
+		log.SetOutput(&logBuf)
+		defer log.SetOutput(GinkgoWriter)
+		log.SetLevel(log.LevelDebug)
+
+		// Act
+		imgURL, err := provider.ArtistImage(ctx, "artist-expired")
+
+		// Assert: returns stale URL immediately, no agent call
+		Expect(err).ToNot(HaveOccurred())
+		Expect(imgURL).To(Equal(expectedURL))
+		mockImageAgent.AssertNotCalled(GinkgoT(), "GetArtistImages", mock.Anything, "artist-expired", mock.Anything, mock.Anything)
+
+		// Assert: background refresh was enqueued
+		Expect(logBuf.String()).To(ContainSubstring("Artist image info expired, enqueuing background refresh"))
+	})
+
 	Context("Unicode handling in artist names", func() {
 		var artistWithEnDash *model.Artist
 		var expectedURL *url.URL
@@ -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"))
-		})
-	})
-})
@@ -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() {
@@ -6,11 +6,11 @@ import (

 	_ "github.com/navidrome/navidrome/adapters/lastfm"
 	_ "github.com/navidrome/navidrome/adapters/listenbrainz"
-	_ "github.com/navidrome/navidrome/adapters/spotify"
 	"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/core/matcher"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -30,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()

@@ -45,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() {
@@ -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
 	})